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