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 June 25, 2012
  36 .Dt STRFTIME 3
  37 .Os
  38 .Sh NAME
  39 .Nm strftime
  40 .Nd format date and time
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In time.h
  45 .Ft size_t
  46 .Fo strftime
  47 .Fa "char * restrict buf"
  48 .Fa "size_t maxsize"
  49 .Fa "const char * restrict format"
  50 .Fa "const struct tm * restrict timeptr"
  51 .Fc
  52 .Ft size_t
  53 .Fn strftime_l "char *restrict buf" "size_t maxsize" "const char * restrict format" "const struct tm *restrict timeptr" "locale_t loc"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn strftime
  57 function formats the information from
  58 .Fa timeptr
  59 into the buffer
  60 .Fa buf
  61 according to the string pointed to by
  62 .Fa format .
  63 The function
  64 .Fn strftime_l
  65 does the same as
  66 .Fn strftime
  67 but takes an explicit locale rather than using the current locale.
  68 .Pp
  69 The
  70 .Fa format
  71 string consists of zero or more conversion specifications and
  72 ordinary characters.
  73 All ordinary characters are copied directly into the buffer.
  74 A conversion specification consists of a percent sign
  75 .Dq Ql %
  76 and one other character.
  77 .Pp
  78 No more than
  79 .Fa maxsize
  80 characters will be placed into the array.
  81 If the total number of resulting characters, including the terminating
  82 NUL character, is not more than
  83 .Fa maxsize ,
  84 .Fn strftime
  85 returns the number of characters in the array, not counting the
  86 terminating NUL.
  87 Otherwise, zero is returned and the buffer contents are indeterminate.
  88 .Pp
  89 The conversion specifications are copied to the buffer after expansion
  90 as follows:-
  91 .Bl -tag -width "xxxx"
  92 .It Cm \&%A
  93 is replaced by national representation of the full weekday name.
  94 .It Cm %a
  95 is replaced by national representation of
  96 the abbreviated weekday name.
  97 .It Cm \&%B
  98 is replaced by national representation of the full month name.
  99 .It Cm %b
 100 is replaced by national representation of
 101 the abbreviated month name.
 102 .It Cm \&%C
 103 is replaced by (year / 100) as decimal number; single
 104 digits are preceded by a zero.
 105 .It Cm %c
 106 is replaced by national representation of time and date.
 107 .It Cm \&%D
 108 is equivalent to
 109 .Dq Li %m/%d/%y .
 110 .It Cm %d
 111 is replaced by the day of the month as a decimal number (01-31).
 112 .It Cm %E* %O*
 113 POSIX locale extensions.
 114 The sequences
 115 %Ec %EC %Ex %EX %Ey %EY
 116 %Od %Oe %OH %OI %Om %OM
 117 %OS %Ou %OU %OV %Ow %OW %Oy
 118 are supposed to provide alternate
 119 representations.
 120 .Pp
 121 Additionally %OB implemented
 122 to represent alternative months names
 123 (used standalone, without day mentioned).
 124 .It Cm %e
 125 is replaced by the day of the month as a decimal number (1-31); single
 126 digits are preceded by a blank.
 127 .It Cm \&%F
 128 is equivalent to
 129 .Dq Li %Y-%m-%d .
 130 .It Cm \&%G
 131 is replaced by a year as a decimal number with century.
 132 This year is the one that contains the greater part of
 133 the week (Monday as the first day of the week).
 134 .It Cm %g
 135 is replaced by the same year as in
 136 .Dq Li %G ,
 137 but as a decimal number without century (00-99).
 138 .It Cm \&%H
 139 is replaced by the hour (24-hour clock) as a decimal number (00-23).
 140 .It Cm %h
 141 the same as
 142 .Cm %b .
 143 .It Cm \&%I
 144 is replaced by the hour (12-hour clock) as a decimal number (01-12).
 145 .It Cm %j
 146 is replaced by the day of the year as a decimal number (001-366).
 147 .It Cm %k
 148 is replaced by the hour (24-hour clock) as a decimal number (0-23);
 149 single digits are preceded by a blank.
 150 .It Cm %l
 151 is replaced by the hour (12-hour clock) as a decimal number (1-12);
 152 single digits are preceded by a blank.
 153 .It Cm \&%M
 154 is replaced by the minute as a decimal number (00-59).
 155 .It Cm %m
 156 is replaced by the month as a decimal number (01-12).
 157 .It Cm %n
 158 is replaced by a newline.
 159 .It Cm %O*
 160 the same as
 161 .Cm %E* .
 162 .It Cm %p
 163 is replaced by national representation of either
 164 "ante meridiem" (a.m.)
 165 or
 166 "post meridiem" (p.m.)
 167 as appropriate.
 168 .It Cm \&%R
 169 is equivalent to
 170 .Dq Li %H:%M .
 171 .It Cm %r
 172 is equivalent to
 173 .Dq Li %I:%M:%S %p .
 174 .It Cm \&%S
 175 is replaced by the second as a decimal number (00-60).
 176 .It Cm %s
 177 is replaced by the number of seconds since the Epoch (see
 178 .Xr ctime 3 ) .
 179 .It Cm \&%T
 180 is equivalent to
 181 .Dq Li %H:%M:%S .
 182 .It Cm %t
 183 is replaced by a tab.
 184 .It Cm \&%U
 185 is replaced by the week number of the year (Sunday as the first day of
 186 the week) as a decimal number (00-53).
 187 .It Cm %u
 188 is replaced by the weekday (Monday as the first day of the week)
 189 as a decimal number (1-7).
 190 .It Cm \&%V
 191 is replaced by the week number of the year (Monday as the first day of
 192 the week) as a decimal number (01-53).
 193 If the week containing January
 194 1 has four or more days in the new year, then it is week 1; otherwise
 195 it is the last week of the previous year, and the next week is week 1.
 196 .It Cm %v
 197 is equivalent to
 198 .Dq Li %e-%b-%Y .
 199 .It Cm \&%W
 200 is replaced by the week number of the year (Monday as the first day of
 201 the week) as a decimal number (00-53).
 202 .It Cm %w
 203 is replaced by the weekday (Sunday as the first day of the week)
 204 as a decimal number (0-6).
 205 .It Cm \&%X
 206 is replaced by national representation of the time.
 207 .It Cm %x
 208 is replaced by national representation of the date.
 209 .It Cm \&%Y
 210 is replaced by the year with century as a decimal number.
 211 .It Cm %y
 212 is replaced by the year without century as a decimal number (00-99).
 213 .It Cm \&%Z
 214 is replaced by the time zone name.
 215 .It Cm %z
 216 is replaced by the offset from the Prime Meridian;
 217 a leading plus sign stands for
 218 east of Greenwich, a minus sign for west of Greenwich,
 219 hours and minutes follow
 220 with two digits each and no delimiter between them (common form for
 221 RFC 822 date headers).
 222 .It Cm %+
 223 is replaced by national representation of the date and time
 224 (the format is similar to that produced by
 225 .Xr date 1 ) .
 226 .It Cm %-*
 227 GNU libc extension.
 228 Do not do any padding when performing numerical outputs.
 229 .It Cm %_*
 230 GNU libc extension.
 231 Explicitly specify space for padding.
 232 .It Cm %0*
 233 GNU libc extension.
 234 Explicitly specify zero for padding.
 235 .It Cm %%
 236 is replaced by
 237 .Ql % .
 238 .El
 239 .Sh SEE ALSO
 240 .Xr date 1 ,
 241 .Xr printf 1 ,
 242 .Xr ctime 3 ,
 243 .Xr printf 3 ,
 244 .Xr strptime 3 ,
 245 .Xr wcsftime 3
 246 .Sh STANDARDS
 247 The
 248 .Fn strftime
 249 function
 250 conforms to
 251 .St -isoC
 252 with a lot of extensions including
 253 .Ql %C ,
 254 .Ql \&%D ,
 255 .Ql %E* ,
 256 .Ql %e ,
 257 .Ql %G ,
 258 .Ql %g ,
 259 .Ql %h ,
 260 .Ql %k ,
 261 .Ql %l ,
 262 .Ql %n ,
 263 .Ql %O* ,
 264 .Ql \&%R ,
 265 .Ql %r ,
 266 .Ql %s ,
 267 .Ql \&%T ,
 268 .Ql %t ,
 269 .Ql %u ,
 270 .Ql \&%V ,
 271 .Ql %z ,
 272 .Ql %+ .
 273 .Pp
 274 The peculiar week number and year in the replacements of
 275 .Ql %G ,
 276 .Ql %g
 277 and
 278 .Ql \&%V
 279 are defined in ISO 8601: 1988.
 280 The
 281 .Fn strftime_l
 282 function conforms to
 283 .St -p1003.1-2008 .
 284 .Sh BUGS
 285 There is no conversion specification for the phase of the moon.
 286 .Pp
 287 The
 288 .Fn strftime
 289 function does not correctly handle multibyte characters in the
 290 .Fa format
 291 argument.