lib/libc/stdtime/strftime.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)strftime.3  8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: head/lib/libc/stdtime/strftime.3 237573 2012-06-25 21:51:40Z issyl0 $
  34 .\"
  35 .Dd December 25, 2013
  36 .Dt STRFTIME 3
  37 .Os
  38 .Sh NAME
  39 .Nm strftime ,
  40 .Nm strftime_l
  41 .Nd format date and time
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In time.h
  46 .Ft size_t
  47 .Fo strftime
  48 .Fa "char * restrict buf"
  49 .Fa "size_t maxsize"
  50 .Fa "const char * restrict format"
  51 .Fa "const struct tm * restrict timeptr"
  52 .Fc
  53 .Ft size_t
  54 .Fn strftime_l "char *restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm *restrict timeptr" "locale_t locale"
  55 .Sh DESCRIPTION
  56 The
  57 .Fn strftime
  58 function formats the information from
  59 .Fa timeptr
  60 into the buffer
  61 .Fa buf
  62 according to the string pointed to by
  63 .Fa format .
  64 The function
  65 .Fn strftime_l
  66 does the same as
  67 .Fn strftime
  68 but takes an explicit
  69 .Fa locale
  70 rather than using the current locale.
  71 .Pp
  72 The
  73 .Fa format
  74 string consists of zero or more conversion specifications and
  75 ordinary characters.
  76 All ordinary characters are copied directly into the buffer.
  77 A conversion specification consists of a percent sign
  78 .Dq Ql %
  79 and one other character.
  80 .Pp
  81 No more than
  82 .Fa maxsize
  83 characters will be placed into the array.
  84 If the total number of resulting characters, including the terminating
  85 NUL character, is not more than
  86 .Fa maxsize ,
  87 .Fn strftime
  88 and
  89 .Fn strftime_l
  90 return the number of characters in the array, not counting the
  91 terminating NUL.
  92 Otherwise, zero is returned and the buffer contents are indeterminate.
  93 .Pp
  94 The conversion specifications are copied to the buffer after expansion
  95 as follows:-
  96 .Bl -tag -width "xxxx"
  97 .It Cm \&%A
  98 is replaced by national representation of the full weekday name.
  99 .It Cm %a
 100 is replaced by national representation of
 101 the abbreviated weekday name.
 102 .It Cm \&%B
 103 is replaced by national representation of the full month name.
 104 .It Cm %b
 105 is replaced by national representation of
 106 the abbreviated month name.
 107 .It Cm \&%C
 108 is replaced by (year / 100) as decimal number; single
 109 digits are preceded by a zero.
 110 .It Cm %c
 111 is replaced by national representation of time and date.
 112 .It Cm \&%D
 113 is equivalent to
 114 .Dq Li %m/%d/%y .
 115 .It Cm %d
 116 is replaced by the day of the month as a decimal number (01-31).
 117 .It Cm %E* %O*
 118 POSIX locale extensions.
 119 The sequences
 120 %Ec %EC %Ex %EX %Ey %EY
 121 %Od %Oe %OH %OI %Om %OM
 122 %OS %Ou %OU %OV %Ow %OW %Oy
 123 are supposed to provide alternate
 124 representations.
 125 .Pp
 126 Additionally %OB implemented
 127 to represent alternative months names
 128 (used standalone, without day mentioned).
 129 .It Cm %e
 130 is replaced by the day of the month as a decimal number (1-31); single
 131 digits are preceded by a blank.
 132 .It Cm \&%F
 133 is equivalent to
 134 .Dq Li %Y-%m-%d .
 135 .It Cm \&%G
 136 is replaced by a year as a decimal number with century.
 137 This year is the one that contains the greater part of
 138 the week (Monday as the first day of the week).
 139 .It Cm %g
 140 is replaced by the same year as in
 141 .Dq Li %G ,
 142 but as a decimal number without century (00-99).
 143 .It Cm \&%H
 144 is replaced by the hour (24-hour clock) as a decimal number (00-23).
 145 .It Cm %h
 146 the same as
 147 .Cm %b .
 148 .It Cm \&%I
 149 is replaced by the hour (12-hour clock) as a decimal number (01-12).
 150 .It Cm %j
 151 is replaced by the day of the year as a decimal number (001-366).
 152 .It Cm %k
 153 is replaced by the hour (24-hour clock) as a decimal number (0-23);
 154 single digits are preceded by a blank.
 155 .It Cm %l
 156 is replaced by the hour (12-hour clock) as a decimal number (1-12);
 157 single digits are preceded by a blank.
 158 .It Cm \&%M
 159 is replaced by the minute as a decimal number (00-59).
 160 .It Cm %m
 161 is replaced by the month as a decimal number (01-12).
 162 .It Cm %n
 163 is replaced by a newline.
 164 .It Cm %O*
 165 the same as
 166 .Cm %E* .
 167 .It Cm %p
 168 is replaced by national representation of either
 169 "ante meridiem" (a.m.)
 170 or
 171 "post meridiem" (p.m.)
 172 as appropriate.
 173 .It Cm \&%R
 174 is equivalent to
 175 .Dq Li %H:%M .
 176 .It Cm %r
 177 is equivalent to
 178 .Dq Li %I:%M:%S %p .
 179 .It Cm \&%S
 180 is replaced by the second as a decimal number (00-60).
 181 .It Cm %s
 182 is replaced by the number of seconds since the Epoch (see
 183 .Xr ctime 3 ) .
 184 .It Cm \&%T
 185 is equivalent to
 186 .Dq Li %H:%M:%S .
 187 .It Cm %t
 188 is replaced by a tab.
 189 .It Cm \&%U
 190 is replaced by the week number of the year (Sunday as the first day of
 191 the week) as a decimal number (00-53).
 192 .It Cm %u
 193 is replaced by the weekday (Monday as the first day of the week)
 194 as a decimal number (1-7).
 195 .It Cm \&%V
 196 is replaced by the week number of the year (Monday as the first day of
 197 the week) as a decimal number (01-53).
 198 If the week containing January
 199 1 has four or more days in the new year, then it is week 1; otherwise
 200 it is the last week of the previous year, and the next week is week 1.
 201 .It Cm %v
 202 is equivalent to
 203 .Dq Li %e-%b-%Y .
 204 .It Cm \&%W
 205 is replaced by the week number of the year (Monday as the first day of
 206 the week) as a decimal number (00-53).
 207 .It Cm %w
 208 is replaced by the weekday (Sunday as the first day of the week)
 209 as a decimal number (0-6).
 210 .It Cm \&%X
 211 is replaced by national representation of the time.
 212 .It Cm %x
 213 is replaced by national representation of the date.
 214 .It Cm \&%Y
 215 is replaced by the year with century as a decimal number.
 216 .It Cm %y
 217 is replaced by the year without century as a decimal number (00-99).
 218 .It Cm \&%Z
 219 is replaced by the time zone name.
 220 .It Cm %z
 221 is replaced by the offset from the Prime Meridian;
 222 a leading plus sign stands for
 223 east of Greenwich, a minus sign for west of Greenwich,
 224 hours and minutes follow
 225 with two digits each and no delimiter between them (common form for
 226 RFC 822 date headers).
 227 .It Cm %+
 228 is replaced by national representation of the date and time
 229 (the format is similar to that produced by
 230 .Xr date 1 ) .
 231 .It Cm %-*
 232 GNU libc extension.
 233 Do not do any padding when performing numerical outputs.
 234 .It Cm %_*
 235 GNU libc extension.
 236 Explicitly specify space for padding.
 237 .It Cm %0*
 238 GNU libc extension.
 239 Explicitly specify zero for padding.
 240 .It Cm %%
 241 is replaced by
 242 .Ql % .
 243 .El
 244 .Sh SEE ALSO
 245 .Xr date 1 ,
 246 .Xr printf 1 ,
 247 .Xr ctime 3 ,
 248 .Xr printf 3 ,
 249 .Xr strptime 3 ,
 250 .Xr wcsftime 3
 251 .Sh STANDARDS
 252 The
 253 .Fn strftime
 254 function
 255 conforms to
 256 .St -isoC
 257 with a lot of extensions including
 258 .Ql %C ,
 259 .Ql \&%D ,
 260 .Ql %E* ,
 261 .Ql %e ,
 262 .Ql %G ,
 263 .Ql %g ,
 264 .Ql %h ,
 265 .Ql %k ,
 266 .Ql %l ,
 267 .Ql %n ,
 268 .Ql %O* ,
 269 .Ql \&%R ,
 270 .Ql %r ,
 271 .Ql %s ,
 272 .Ql \&%T ,
 273 .Ql %t ,
 274 .Ql %u ,
 275 .Ql \&%V ,
 276 .Ql %z ,
 277 .Ql %+ .
 278 .Pp
 279 The peculiar week number and year in the replacements of
 280 .Ql %G ,
 281 .Ql %g
 282 and
 283 .Ql \&%V
 284 are defined in ISO 8601: 1988.
 285 The
 286 .Fn strftime_l
 287 function conforms to
 288 .St -p1003.1-2008 .
 289 .Sh BUGS
 290 There is no conversion specification for the phase of the moon.
 291 .Pp
 292 The
 293 .Fn strftime
 294 and
 295 .Fn strftime_l
 296 functions do not correctly handle multibyte characters in the
 297 .Fa format
 298 argument.