man3/strftime.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\"     GNU texinfo documentation on glibc date/time functions.
  30 .\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu)
  31 .\" Applied fix by Wolfgang Franke, aeb, 961011
  32 .\" Corrected return value, aeb, 970307
  33 .\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329.
  34 .\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
  35 .\"           'width' components of conversion specifications.
  36 .\"
  37 .TH STRFTIME 3  2015-03-02 "GNU" "Linux Programmer's Manual"
  38 .SH NAME
  39 strftime \- format date and time
  40 .SH SYNOPSIS
  41 .nf
  42 .B #include <time.h>
  43 .sp
  44 .BI "size_t strftime(char *" s ", size_t " max ", const char *" format ,
  45 .BI "                const struct tm *" tm );
  46 .fi
  47 .SH DESCRIPTION
  48 The
  49 .BR strftime ()
  50 function formats the broken-down time
  51 .I tm
  52 according to the format specification
  53 .I format
  54 and places the
  55 result in the character array
  56 .I s
  57 of size
  58 .IR max .
  59 .\" FIXME . POSIX says: Local timezone information is used as though
  60 .\" strftime() called tzset().  But this doesn't appear to be the case
  61 .PP
  62 The format specification is a null-terminated string and may contain
  63 special character sequences called
  64 .IR "conversion specifications",
  65 each of which is introduced by a \(aq%\(aq character and terminated by
  66 some other character known as a
  67 .IR "conversion specifier character".
  68 All other character sequences are
  69 .IR "ordinary character sequences".
  70 .PP
  71 The characters of ordinary character sequences (including the null byte)
  72 are copied verbatim from
  73 .I format
  74 to
  75 .IR s .
  76 However, the characters
  77 of conversion specifications are replaced as follows:
  78 .TP
  79 .B %a
  80 The abbreviated name of the day of the week according to the current locale.
  81 .TP
  82 .B %A
  83 The full name of the day of the week according to the current locale.
  84 .TP
  85 .B %b
  86 The abbreviated month name according to the current locale.
  87 .TP
  88 .B %B
  89 The full month name according to the current locale.
  90 .TP
  91 .B %c
  92 The preferred date and time representation for the current locale.
  93 .TP
  94 .B %C
  95 The century number (year/100) as a 2-digit integer. (SU)
  96 .TP
  97 .B %d
  98 The day of the month as a decimal number (range 01 to 31).
  99 .TP
 100 .B %D
 101 Equivalent to
 102 .BR %m/%d/%y .
 103 (Yecch\(emfor Americans only.
 104 Americans should note that in other countries
 105 .B %d/%m/%y
 106 is rather common.
 107 This means that in international context this format is
 108 ambiguous and should not be used.) (SU)
 109 .TP
 110 .B %e
 111 Like
 112 .BR %d ,
 113 the day of the month as a decimal number, but a leading
 114 zero is replaced by a space. (SU)
 115 .TP
 116 .B %E
 117 Modifier: use alternative format, see below. (SU)
 118 .TP
 119 .B %F
 120 Equivalent to
 121 .B %Y-%m-%d
 122 (the ISO\ 8601 date format). (C99)
 123 .TP
 124 .B %G
 125 The ISO\ 8601 week-based year (see NOTES) with century as a decimal number.
 126 The 4-digit year corresponding to the ISO week number (see
 127 .BR %V ).
 128 This has the same format and value as
 129 .BR %Y ,
 130 except that if the ISO week number belongs to the previous or next year,
 131 that year is used instead. (TZ)
 132 .TP
 133 .B %g
 134 Like
 135 .BR %G ,
 136 but without century, that is, with a 2-digit year (00-99). (TZ)
 137 .TP
 138 .B %h
 139 Equivalent to
 140 .BR %b .
 141 (SU)
 142 .TP
 143 .B %H
 144 The hour as a decimal number using a 24-hour clock (range 00 to 23).
 145 .TP
 146 .B %I
 147 The hour as a decimal number using a 12-hour clock (range 01 to 12).
 148 .TP
 149 .B %j
 150 The day of the year as a decimal number (range 001 to 366).
 151 .TP
 152 .B %k
 153 The hour (24-hour clock) as a decimal number (range 0 to 23);
 154 single digits are preceded by a blank.
 155 (See also
 156 .BR %H .)
 157 (TZ)
 158 .TP
 159 .B %l
 160 The hour (12-hour clock) as a decimal number (range 1 to 12);
 161 single digits are preceded by a blank.
 162 (See also
 163 .BR %I .)
 164 (TZ)
 165 .TP
 166 .B %m
 167 The month as a decimal number (range 01 to 12).
 168 .TP
 169 .B %M
 170 The minute as a decimal number (range 00 to 59).
 171 .TP
 172 .B %n
 173 A newline character. (SU)
 174 .TP
 175 .B %O
 176 Modifier: use alternative format, see below. (SU)
 177 .TP
 178 .B %p
 179 Either "AM" or "PM" according to the given time value, or the
 180 corresponding strings for the current locale.
 181 Noon is treated as "PM" and midnight as "AM".
 182 .TP
 183 .B %P
 184 Like
 185 .B %p
 186 but in lowercase: "am" or "pm" or a corresponding
 187 string for the current locale. (GNU)
 188 .TP
 189 .B %r
 190 The time in a.m. or p.m. notation.
 191 In the POSIX locale this is equivalent to
 192 .BR "%I:%M:%S %p" .
 193 (SU)
 194 .TP
 195 .B %R
 196 The time in 24-hour notation
 197 .RB ( %H:%M ).
 198 (SU)
 199 For a version including the seconds, see
 200 .B %T
 201 below.
 202 .TP
 203 .B %s
 204 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
 205 .TP
 206 .B %S
 207 The second as a decimal number (range 00 to 60).
 208 (The range is up to 60 to allow for occasional leap seconds.)
 209 .TP
 210 .B %t
 211 A tab character. (SU)
 212 .TP
 213 .B %T
 214 The time in 24-hour notation
 215 .RB ( %H:%M:%S ).
 216 (SU)
 217 .TP
 218 .B %u
 219 The day of the week as a decimal, range 1 to 7, Monday being 1.
 220 See also
 221 .BR %w .
 222 (SU)
 223 .TP
 224 .B %U
 225 The week number of the current year as a decimal number,
 226 range 00 to 53, starting with the first Sunday as the first day
 227 of week 01.
 228 See also
 229 .B %V
 230 and
 231 .BR %W .
 232 .TP
 233 .B %V
 234 The ISO\ 8601 week number (see NOTES) of the current year as a decimal number,
 235 range 01 to 53, where week 1 is the first week that has at least
 236 4 days in the new year.
 237 See also
 238 .B %U
 239 and
 240 .BR %W .
 241 (SU)
 242 .TP
 243 .B %w
 244 The day of the week as a decimal, range 0 to 6, Sunday being 0.
 245 See also
 246 .BR %u .
 247 .TP
 248 .B %W
 249 The week number of the current year as a decimal number,
 250 range 00 to 53, starting with the first Monday as the first day of week 01.
 251 .TP
 252 .B %x
 253 The preferred date representation for the current locale without the time.
 254 .TP
 255 .B %X
 256 The preferred time representation for the current locale without the date.
 257 .TP
 258 .B %y
 259 The year as a decimal number without a century (range 00 to 99).
 260 .TP
 261 .B %Y
 262 The year as a decimal number including the century.
 263 .TP
 264 .B %z
 265 The
 266 .I +hhmm
 267 or
 268 .I -hhmm
 269 numeric timezone (that is, the hour and minute offset from UTC). (SU)
 270 .TP
 271 .B %Z
 272 The timezone name or abbreviation.
 273 .TP
 274 .B %+
 275 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
 276 .\" their man pages)
 277 The date and time in
 278 .BR date (1)
 279 format. (TZ)
 280 (Not supported in glibc2.)
 281 .TP
 282 .B %%
 283 A literal \(aq%\(aq character.
 284 .PP
 285 Some conversion specifications can be modified by preceding the
 286 conversion specifier character by the
 287 .B E
 288 or
 289 .B O
 290 .I modifier
 291 to indicate that an alternative format should be used.
 292 If the alternative format or specification does not exist for
 293 the current locale, the behavior will be as if the unmodified
 294 conversion specification were used. (SU)
 295 The Single UNIX Specification mentions
 296 .BR %Ec ,
 297 .BR %EC ,
 298 .BR %Ex ,
 299 .BR %EX ,
 300 .BR %Ey ,
 301 .BR %EY ,
 302 .BR %Od ,
 303 .BR %Oe ,
 304 .BR %OH ,
 305 .BR %OI ,
 306 .BR %Om ,
 307 .BR %OM ,
 308 .BR %OS ,
 309 .BR %Ou ,
 310 .BR %OU ,
 311 .BR %OV ,
 312 .BR %Ow ,
 313 .BR %OW ,
 314 .BR %Oy ,
 315 where the effect of the
 316 .B O
 317 modifier is to use
 318 alternative numeric symbols (say, roman numerals), and that of the
 319 E modifier is to use a locale-dependent alternative representation.
 320 .PP
 321 The broken-down time structure
 322 .I tm
 323 is defined in
 324 .IR <time.h> .
 325 See also
 326 .BR ctime (3).
 327 .SH RETURN VALUE
 328 Provided that the result string,
 329 including the terminating null byte, does not exceed
 330 .I max
 331 bytes,
 332 .BR strftime ()
 333 returns the number of bytes (excluding the terminating null byte)
 334 placed in the array
 335 .IR s .
 336 If the length of the result string (including the terminating null byte)
 337 would exceed
 338 .I max
 339 bytes, then
 340 .BR strftime ()
 341 returns 0, and the contents of the array are undefined.
 342 .\" (This behavior applies since at least libc 4.4.4;
 343 .\" very old versions of libc, such as libc 4.4.1,
 344 .\" would return
 345 .\" .I max
 346 .\" if the array was too small.)
 347 .LP
 348 Note that the return value 0 does not necessarily indicate an error.
 349 For example, in many locales
 350 .B %p
 351 yields an empty string.
 352 An empty
 353 .I format
 354 string will likewise yield an empty string.
 355 .SH ENVIRONMENT
 356 The environment variables
 357 .B TZ
 358 and
 359 .B LC_TIME
 360 are used.
 361 .SH ATTRIBUTES
 362 For an explanation of the terms used in this section, see
 363 .BR attributes (7).
 364 .TS
 365 allbox;
 366 lb lb lb
 367 l l l.
 368 Interface       Attribute       Value
 369 T{
 370 .BR strftime ()
 371 T}      Thread safety   MT-Safe env locale
 372 .TE
 373 .SH CONFORMING TO
 374 SVr4, C89, C99.
 375 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
 376 .\" in the standards changed across kernel versions. Investigate and
 377 .\" write up.
 378 There are strict inclusions between the set of conversions
 379 given in ANSI C (unmarked), those given in the Single UNIX Specification
 380 (marked SU), those given in Olson's timezone package (marked TZ),
 381 and those given in glibc (marked GNU), except that
 382 .B %+
 383 is not supported in glibc2.
 384 On the other hand glibc2 has several more extensions.
 385 POSIX.1 only refers to ANSI C; POSIX.2 describes under
 386 .BR date (1)
 387 several extensions that could apply to
 388 .BR strftime ()
 389 as well.
 390 The
 391 .B %F
 392 conversion is in C99 and POSIX.1-2001.
 393
 394 In SUSv2, the
 395 .B %S
 396 specifier allowed a range of 00 to 61,
 397 to allow for the theoretical possibility of a minute that
 398 included a double leap second
 399 (there never has been such a minute).
 400 .SH NOTES
 401 .SS ISO 8601 week dates
 402 .BR %G ,
 403 .BR %g ,
 404 and
 405 .BR %V
 406 yield values calculated from the week-based year defined by the
 407 ISO\ 8601 standard.
 408 In this system, weeks start on a Monday, and are numbered from 01,
 409 for the first week, up to 52 or 53, for the last week.
 410 Week 1 is the first week where four or more days fall within the
 411 new year (or, synonymously, week 01 is:
 412 the first week of the year that contains a Thursday;
 413 or, the week that has 4 January in it).
 414 When three of fewer days of the first calendar week of the new year fall
 415 within that year,
 416 then the ISO 8601 week-based system counts those days as part of week 53
 417 of the preceding year.
 418 For example, 1 January 2010 is a Friday,
 419 meaning that just three days of that calendar week fall in 2010.
 420 Thus, the ISO\ 8601 week-based system considers these days to be part of
 421 week 53
 422 .RB ( %V )
 423 of the year 2009
 424 .RB ( %G );
 425 week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
 426 .SS Glibc notes
 427 Glibc provides some extensions for conversion specifications.
 428 (These extensions are not specified in POSIX.1-2001, but a few other
 429 systems provide similar features.)
 430 .\" HP-UX and Tru64 also have features like this.
 431 Between the \(aq%\(aq character and the conversion specifier character,
 432 an optional
 433 .I flag
 434 and field
 435 .I width
 436 may be specified.
 437 (These precede the
 438 .B E
 439 or
 440 .B O
 441 modifiers, if present.)
 442
 443 The following flag characters are permitted:
 444 .TP
 445 .B _
 446 (underscore)
 447 Pad a numeric result string with spaces.
 448 .TP
 449 .B \-
 450 (dash)
 451 Do not pad a numeric result string.
 452 .TP
 453 .B 0
 454 Pad a numeric result string with zeros even if the conversion
 455 specifier character uses space-padding by default.
 456 .TP
 457 .B ^
 458 Convert alphabetic characters in result string to uppercase.
 459 .TP
 460 .B #
 461 Swap the case of the result string.
 462 (This flag works only with certain conversion specifier characters,
 463 and of these, it is only really useful with
 464 .BR %Z .)
 465 .PP
 466 An optional decimal width specifier may follow the (possibly absent) flag.
 467 If the natural size of the field is smaller than this width,
 468 then the result string is padded (on the left) to the specified width.
 469 .SH BUGS
 470 If the output string would exceed
 471 .I max
 472 bytes,
 473 .I errno
 474 is
 475 .I not
 476 set.
 477 This makes it impossible to distinguish this error case from cases where the
 478 .I format
 479 string legitimately produces a zero-length output string.
 480 POSIX.1-2001
 481 does
 482 .I not
 483 specify any
 484 .I errno
 485 settings for
 486 .BR strftime ().
 487
 488 Some buggy versions of
 489 .BR gcc (1)
 490 complain about the use of
 491 .BR %c :
 492 .IR "warning: `%c' yields only last 2 digits of year in some locales" .
 493 Of course programmers are encouraged to use
 494 .BR %c ,
 495 it gives the preferred date and time representation.
 496 One meets all kinds of strange obfuscations
 497 to circumvent this
 498 .BR gcc (1)
 499 problem.
 500 A relatively clean one is to add an
 501 intermediate function
 502 .in +4n
 503 .nf
 504
 505 size_t
 506 my_strftime(char *s, size_t max, const char *fmt,
 507             const struct tm *tm)
 508 {
 509     return strftime(s, max, fmt, tm);
 510 }
 511 .fi
 512 .in
 513
 514 Nowadays,
 515 .BR gcc (1)
 516 provides the
 517 .IR \-Wno\-format\-y2k
 518 option to prevent the warning,
 519 so that the above workaround is no longer required.
 520 .SH EXAMPLE
 521 .BR "RFC\ 2822-compliant date format"
 522 (with an English locale for %a and %b)
 523 .PP
 524 .in +2n
 525 "%a,\ %d\ %b\ %Y\ %T\ %z"
 526 .PP
 527 .BR "RFC\ 822-compliant date format"
 528 (with an English locale for %a and %b)
 529 .PP
 530 .in +2n
 531 "%a,\ %d\ %b\ %y\ %T\ %z"
 532 .SS Example program
 533 The program below can be used to experiment with
 534 .BR strftime ().
 535 .PP
 536 Some examples of the result string produced by the glibc implementation of
 537 .BR strftime ()
 538 are as follows:
 539 .in +4n
 540 .nf
 541
 542 .RB "$" " ./a.out \(aq%m\(aq"
 543 Result string is "11"
 544 .RB "$" " ./a.out \(aq%5m\(aq"
 545 Result string is "00011"
 546 .RB "$" " ./a.out \(aq%_5m\(aq"
 547 Result string is "   11"
 548 .fi
 549 .in
 550 .SS Program source
 551 .nf
 552 #include <time.h>
 553 #include <stdio.h>
 554 #include <stdlib.h>
 555
 556 int
 557 main(int argc, char *argv[])
 558 {
 559     char outstr[200];
 560     time_t t;
 561     struct tm *tmp;
 562
 563     t = time(NULL);
 564     tmp = localtime(&t);
 565     if (tmp == NULL) {
 566         perror("localtime");
 567         exit(EXIT_FAILURE);
 568     }
 569
 570     if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
 571         fprintf(stderr, "strftime returned 0");
 572         exit(EXIT_FAILURE);
 573     }
 574
 575     printf("Result string is \\"%s\\"\\n", outstr);
 576     exit(EXIT_SUCCESS);
 577 }
 578 .fi
 579 .SH SEE ALSO
 580 .BR date (1),
 581 .BR time (2),
 582 .BR ctime (3),
 583 .BR setlocale (3),
 584 .BR sprintf (3),
 585 .BR strptime (3)