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