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