man3/strftime.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\"     GNU texinfo documentation on glibc date/time functions.
  10 .\" Modified Sat Jul 24 18:03:44 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Applied fix by Wolfgang Franke, aeb, 961011
  12 .\" Corrected return value, aeb, 970307
  13 .\" Added Single UNIX Spec conversions and %z, aeb/esr, 990329.
  14 .\" 2005-11-22 mtk, added Glibc Notes covering optional 'flag' and
  15 .\"           'width' components of conversion specifications.
  16 .\"
  17 .TH STRFTIME 3  2021-03-22 "Linux man-pages (unreleased)"
  18 .SH NAME
  19 strftime \- format date and time
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <time.h>
  26 .PP
  27 .BI "size_t strftime(char *restrict " s ", size_t " max ,
  28 .BI "                const char *restrict " format ,
  29 .BI "                const struct tm *restrict " tm );
  30 .PP
  31 .BI "size_t strftime_l(char *restrict " s ", size_t " max ,
  32 .BI "                const char *restrict " format ,
  33 .BI "                const struct tm *restrict " tm ,
  34 .BI "                locale_t " locale );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR strftime ()
  39 function formats the broken-down time
  40 .I tm
  41 according to the format specification
  42 .I format
  43 and places the
  44 result in the character array
  45 .I s
  46 of size
  47 .IR max .
  48 The broken-down time structure
  49 .I tm
  50 is defined in
  51 .IR <time.h> .
  52 See also
  53 .BR ctime (3).
  54 .\" FIXME . POSIX says: Local timezone information is used as though
  55 .\" strftime() called tzset().  But this doesn't appear to be the case
  56 .PP
  57 The format specification is a null-terminated string and may contain
  58 special character sequences called
  59 .IR "conversion specifications",
  60 each of which is introduced by a \(aq%\(aq character and terminated by
  61 some other character known as a
  62 .IR "conversion specifier character".
  63 All other character sequences are
  64 .IR "ordinary character sequences".
  65 .PP
  66 The characters of ordinary character sequences (including the null byte)
  67 are copied verbatim from
  68 .I format
  69 to
  70 .IR s .
  71 However, the characters
  72 of conversion specifications are replaced as shown in the list below.
  73 In this list, the field(s) employed from the
  74 .I tm
  75 structure are also shown.
  76 .TP
  77 .B %a
  78 The abbreviated name of the day of the week according to the current locale.
  79 (Calculated from
  80 .IR tm_wday .)
  81 (The specific names used in the current locale can be obtained by calling
  82 .BR nl_langinfo (3)
  83 with
  84 .BR ABDAY_ { 1 \(en 7 }
  85 as an argument.)
  86 .TP
  87 .B %A
  88 The full name of the day of the week according to the current locale.
  89 (Calculated from
  90 .IR tm_wday .)
  91 (The specific names used in the current locale can be obtained by calling
  92 .BR nl_langinfo (3)
  93 with
  94 .BR DAY_ { 1 \(en 7 }
  95 as an argument.)
  96 .TP
  97 .B %b
  98 The abbreviated month name according to the current locale.
  99 (Calculated from
 100 .IR tm_mon .)
 101 (The specific names used in the current locale can be obtained by calling
 102 .BR nl_langinfo (3)
 103 with
 104 .BR ABMON_ { 1 \(en 12 }
 105 as an argument.)
 106 .TP
 107 .B %B
 108 The full month name according to the current locale.
 109 (Calculated from
 110 .IR tm_mon .)
 111 (The specific names used in the current locale can be obtained by calling
 112 .BR nl_langinfo (3)
 113 with
 114 .BR MON_ { 1 \(en 12 }
 115 as an argument.)
 116 .TP
 117 .B %c
 118 The preferred date and time representation for the current locale.
 119 (The specific format used in the current locale can be obtained by calling
 120 .BR nl_langinfo (3)
 121 with
 122 .B D_T_FMT
 123 as an argument for the
 124 .B %c
 125 conversion specification, and with
 126 .B ERA_D_T_FMT
 127 for the
 128 .B %Ec
 129 conversion specification.)
 130 (In the POSIX locale this is equivalent to
 131 .BR "%a %b %e %H:%M:%S %Y" .)
 132 .TP
 133 .B %C
 134 The century number (year/100) as a 2-digit integer. (SU)
 135 (The
 136 .B %EC
 137 conversion specification corresponds to the name of the era.)
 138 (Calculated from
 139 .IR tm_year .)
 140 .TP
 141 .B %d
 142 The day of the month as a decimal number (range 01 to 31).
 143 (Calculated from
 144 .IR tm_mday .)
 145 .TP
 146 .B %D
 147 Equivalent to
 148 .BR %m/%d/%y .
 149 (Yecch\(emfor Americans only.
 150 Americans should note that in other countries
 151 .B %d/%m/%y
 152 is rather common.
 153 This means that in international context this format is
 154 ambiguous and should not be used.) (SU)
 155 .TP
 156 .B %e
 157 Like
 158 .BR %d ,
 159 the day of the month as a decimal number, but a leading
 160 zero is replaced by a space. (SU)
 161 (Calculated from
 162 .IR tm_mday .)
 163 .TP
 164 .B %E
 165 Modifier: use alternative ("era-based") format, see below. (SU)
 166 .TP
 167 .B %F
 168 Equivalent to
 169 .B %Y\-%m\-%d
 170 (the ISO\ 8601 date format). (C99)
 171 .TP
 172 .B %G
 173 The ISO\ 8601 week-based year (see NOTES) with century as a decimal number.
 174 The 4-digit year corresponding to the ISO week number (see
 175 .BR %V ).
 176 This has the same format and value as
 177 .BR %Y ,
 178 except that if the ISO week number belongs to the previous or next year,
 179 that year is used instead. (TZ)
 180 (Calculated from
 181 .IR tm_year ,
 182 .IR tm_yday ,
 183 and
 184 .IR tm_wday .)
 185 .TP
 186 .B %g
 187 Like
 188 .BR %G ,
 189 but without century, that is, with a 2-digit year (00\(en99). (TZ)
 190 (Calculated from
 191 .IR tm_year ,
 192 .IR tm_yday ,
 193 and
 194 .IR tm_wday .)
 195 .TP
 196 .B %h
 197 Equivalent to
 198 .BR %b .
 199 (SU)
 200 .TP
 201 .B %H
 202 The hour as a decimal number using a 24-hour clock (range 00 to 23).
 203 (Calculated from
 204 .IR tm_hour .)
 205 .TP
 206 .B %I
 207 The hour as a decimal number using a 12-hour clock (range 01 to 12).
 208 (Calculated from
 209 .IR tm_hour .)
 210 .TP
 211 .B %j
 212 The day of the year as a decimal number (range 001 to 366).
 213 (Calculated from
 214 .IR tm_yday .)
 215 .TP
 216 .B %k
 217 The hour (24-hour clock) as a decimal number (range 0 to 23);
 218 single digits are preceded by a blank.
 219 (See also
 220 .BR %H .)
 221 (Calculated from
 222 .IR tm_hour .)
 223 (TZ)
 224 .TP
 225 .B %l
 226 The hour (12-hour clock) as a decimal number (range 1 to 12);
 227 single digits are preceded by a blank.
 228 (See also
 229 .BR %I .)
 230 (Calculated from
 231 .IR tm_hour .)
 232 (TZ)
 233 .TP
 234 .B %m
 235 The month as a decimal number (range 01 to 12).
 236 (Calculated from
 237 .IR tm_mon .)
 238 .TP
 239 .B %M
 240 The minute as a decimal number (range 00 to 59).
 241 (Calculated from
 242 .IR tm_min .)
 243 .TP
 244 .B %n
 245 A newline character. (SU)
 246 .TP
 247 .B %O
 248 Modifier: use alternative numeric symbols, see below. (SU)
 249 .TP
 250 .B %p
 251 Either "AM" or "PM" according to the given time value, or the
 252 corresponding strings for the current locale.
 253 Noon is treated as "PM" and midnight as "AM".
 254 (Calculated from
 255 .IR tm_hour .)
 256 (The specific string representations used for "AM" and "PM"
 257 in the current locale can be obtained by calling
 258 .BR nl_langinfo (3)
 259 with
 260 .BR AM_STR " and " PM_STR ,
 261 respectively.)
 262 .TP
 263 .B %P
 264 Like
 265 .B %p
 266 but in lowercase: "am" or "pm" or a corresponding
 267 string for the current locale.
 268 (Calculated from
 269 .IR tm_hour .)
 270 (GNU)
 271 .TP
 272 .B %r
 273 The time in a.m. or p.m. notation.
 274 (SU)
 275 (The specific format used in the current locale can be obtained by calling
 276 .BR nl_langinfo (3)
 277 with
 278 .B T_FMT_AMPM
 279 as an argument.)
 280 (In the POSIX locale this is equivalent to
 281 .BR "%I:%M:%S %p" .)
 282 .TP
 283 .B %R
 284 The time in 24-hour notation
 285 .RB ( %H:%M ).
 286 (SU)
 287 For a version including the seconds, see
 288 .B %T
 289 below.
 290 .TP
 291 .B %s
 292 The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)
 293 (Calculated from
 294 .IR mktime(tm) .)
 295 .TP
 296 .B %S
 297 The second as a decimal number (range 00 to 60).
 298 (The range is up to 60 to allow for occasional leap seconds.)
 299 (Calculated from
 300 .IR tm_sec .)
 301 .TP
 302 .B %t
 303 A tab character. (SU)
 304 .TP
 305 .B %T
 306 The time in 24-hour notation
 307 .RB ( %H:%M:%S ).
 308 (SU)
 309 .TP
 310 .B %u
 311 The day of the week as a decimal, range 1 to 7, Monday being 1.
 312 See also
 313 .BR %w .
 314 (Calculated from
 315 .IR tm_wday .)
 316 (SU)
 317 .TP
 318 .B %U
 319 The week number of the current year as a decimal number,
 320 range 00 to 53, starting with the first Sunday as the first day
 321 of week 01.
 322 See also
 323 .B %V
 324 and
 325 .BR %W .
 326 (Calculated from
 327 .I tm_yday
 328 and
 329 .IR tm_wday .)
 330 .TP
 331 .B %V
 332 The ISO\ 8601 week number (see NOTES) of the current year as a decimal number,
 333 range 01 to 53, where week 1 is the first week that has at least
 334 4 days in the new year.
 335 See also
 336 .B %U
 337 and
 338 .BR %W .
 339 (Calculated from
 340 .IR tm_year ,
 341 .IR tm_yday ,
 342 and
 343 .IR tm_wday .)
 344 (SU)
 345 .TP
 346 .B %w
 347 The day of the week as a decimal, range 0 to 6, Sunday being 0.
 348 See also
 349 .BR %u .
 350 (Calculated from
 351 .IR tm_wday .)
 352 .TP
 353 .B %W
 354 The week number of the current year as a decimal number,
 355 range 00 to 53, starting with the first Monday as the first day of week 01.
 356 (Calculated from
 357 .I tm_yday
 358 and
 359 .IR tm_wday .)
 360 .TP
 361 .B %x
 362 The preferred date representation for the current locale without the time.
 363 (The specific format used in the current locale can be obtained by calling
 364 .BR nl_langinfo (3)
 365 with
 366 .B D_FMT
 367 as an argument for the
 368 .B %x
 369 conversion specification, and with
 370 .B ERA_D_FMT
 371 for the
 372 .B %Ex
 373 conversion specification.)
 374 (In the POSIX locale this is equivalent to
 375 .BR %m/%d/%y .)
 376 .TP
 377 .B %X
 378 The preferred time representation for the current locale without the date.
 379 (The specific format used in the current locale can be obtained by calling
 380 .BR nl_langinfo (3)
 381 with
 382 .B T_FMT
 383 as an argument for the
 384 .B %X
 385 conversion specification, and with
 386 .B ERA_T_FMT
 387 for the
 388 .B %EX
 389 conversion specification.)
 390 (In the POSIX locale this is equivalent to
 391 .BR %H:%M:%S .)
 392 .TP
 393 .B %y
 394 The year as a decimal number without a century (range 00 to 99).
 395 (The
 396 .B %Ey
 397 conversion specification corresponds to the year since the beginning of the era
 398 denoted by the
 399 .B %EC
 400 conversion specification.)
 401 (Calculated from
 402 .IR tm_year )
 403 .TP
 404 .B %Y
 405 The year as a decimal number including the century.
 406 (The
 407 .B %EY
 408 conversion specification corresponds to
 409 the full alternative year representation.)
 410 (Calculated from
 411 .IR tm_year )
 412 .TP
 413 .B %z
 414 The
 415 .I +hhmm
 416 or
 417 .I \-hhmm
 418 numeric timezone (that is, the hour and minute offset from UTC). (SU)
 419 .TP
 420 .B %Z
 421 The timezone name or abbreviation.
 422 .TP
 423 .B %+
 424 .\" Nov 05 -- Not in Linux/glibc, but is in some BSDs (according to
 425 .\" their man pages)
 426 The date and time in
 427 .BR date (1)
 428 format. (TZ)
 429 (Not supported in glibc2.)
 430 .TP
 431 .B %%
 432 A literal \(aq%\(aq character.
 433 .PP
 434 Some conversion specifications can be modified by preceding the
 435 conversion specifier character by the
 436 .B E
 437 or
 438 .B O
 439 .I modifier
 440 to indicate that an alternative format should be used.
 441 If the alternative format or specification does not exist for
 442 the current locale, the behavior will be as if the unmodified
 443 conversion specification were used. (SU)
 444 The Single UNIX Specification mentions
 445 .BR %Ec ,
 446 .BR %EC ,
 447 .BR %Ex ,
 448 .BR %EX ,
 449 .BR %Ey ,
 450 .BR %EY ,
 451 .BR %Od ,
 452 .BR %Oe ,
 453 .BR %OH ,
 454 .BR %OI ,
 455 .BR %Om ,
 456 .BR %OM ,
 457 .BR %OS ,
 458 .BR %Ou ,
 459 .BR %OU ,
 460 .BR %OV ,
 461 .BR %Ow ,
 462 .BR %OW ,
 463 .BR %Oy ,
 464 where the effect of the
 465 .B O
 466 modifier is to use
 467 alternative numeric symbols (say, roman numerals), and that of the
 468 .B E
 469 modifier is to use a locale-dependent alternative representation.
 470 The rules governing date representation with the
 471 .B E
 472 modifier can be obtained by supplying
 473 .B ERA
 474 as an argument to a
 475 .BR nl_langinfo (3).
 476 One example of such alternative forms is the Japanese era calendar scheme in the
 477 .B ja_JP
 478 glibc locale.
 479 .PP
 480 .BR strftime_l ()
 481 is equivalent to
 482 .BR strftime (),
 483 except it uses the specified
 484 .I locale
 485 instead of the current locale.
 486 The behaviour is undefined if
 487 .I locale
 488 is invalid or
 489 .BR LC_GLOBAL_LOCALE .
 490 .SH RETURN VALUE
 491 Provided that the result string,
 492 including the terminating null byte, does not exceed
 493 .I max
 494 bytes,
 495 .BR strftime ()
 496 returns the number of bytes (excluding the terminating null byte)
 497 placed in the array
 498 .IR s .
 499 If the length of the result string (including the terminating null byte)
 500 would exceed
 501 .I max
 502 bytes, then
 503 .BR strftime ()
 504 returns 0, and the contents of the array are undefined.
 505 .\" (This behavior applies since at least libc 4.4.4;
 506 .\" very old versions of libc, such as libc 4.4.1,
 507 .\" would return
 508 .\" .I max
 509 .\" if the array was too small.)
 510 .PP
 511 Note that the return value 0 does not necessarily indicate an error.
 512 For example, in many locales
 513 .B %p
 514 yields an empty string.
 515 An empty
 516 .I format
 517 string will likewise yield an empty string.
 518 .SH ENVIRONMENT
 519 The environment variables
 520 .B TZ
 521 and
 522 .B LC_TIME
 523 are used.
 524 .SH ATTRIBUTES
 525 For an explanation of the terms used in this section, see
 526 .BR attributes (7).
 527 .ad l
 528 .nh
 529 .TS
 530 allbox;
 531 lbx lb lb
 532 l l l.
 533 Interface       Attribute       Value
 534 T{
 535 .BR strftime (),
 536 .BR strftime_l ()
 537 T}      Thread safety   MT-Safe env locale
 538 .TE
 539 .hy
 540 .ad
 541 .sp 1
 542 .SH STANDARDS
 543 .BR strftime ():
 544 SVr4, C89, C99.
 545 .PD 0
 546 .PP
 547 .PD
 548 .BR strftime_l ():
 549 POSIX.1-2008.
 550 .PP
 551 .\" FIXME strftime() is in POSIX.1-2001 and POSIX.1-2008, but the details
 552 .\" in the standards changed across versions. Investigate and
 553 .\" write up.
 554 There are strict inclusions between the set of conversions
 555 given in ANSI C (unmarked), those given in the Single UNIX Specification
 556 (marked SU), those given in Olson's timezone package (marked TZ),
 557 and those given in glibc (marked GNU), except that
 558 .B %+
 559 is not supported in glibc2.
 560 On the other hand glibc2 has several more extensions.
 561 POSIX.1 only refers to ANSI C; POSIX.2 describes under
 562 .BR date (1)
 563 several extensions that could apply to
 564 .BR strftime ()
 565 as well.
 566 The
 567 .B %F
 568 conversion is in C99 and POSIX.1-2001.
 569 .PP
 570 In SUSv2, the
 571 .B %S
 572 specifier allowed a range of 00 to 61,
 573 to allow for the theoretical possibility of a minute that
 574 included a double leap second
 575 (there never has been such a minute).
 576 .SH NOTES
 577 .SS ISO 8601 week dates
 578 .BR %G ,
 579 .BR %g ,
 580 and
 581 .B %V
 582 yield values calculated from the week-based year defined by the
 583 ISO\ 8601 standard.
 584 In this system, weeks start on a Monday, and are numbered from 01,
 585 for the first week, up to 52 or 53, for the last week.
 586 Week 1 is the first week where four or more days fall within the
 587 new year (or, synonymously, week 01 is:
 588 the first week of the year that contains a Thursday;
 589 or, the week that has 4 January in it).
 590 When three or fewer days of the first calendar week of the new year fall
 591 within that year,
 592 then the ISO 8601 week-based system counts those days as part of week 52
 593 or 53 of the preceding year.
 594 For example, 1 January 2010 is a Friday,
 595 meaning that just three days of that calendar week fall in 2010.
 596 Thus, the ISO\ 8601 week-based system considers these days to be part of
 597 week 53
 598 .RB ( %V )
 599 of the year 2009
 600 .RB ( %G );
 601 week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
 602 Similarly, the first two days of January 2011 are considered to be part
 603 of week 52 of the year 2010.
 604 .SS Glibc notes
 605 Glibc provides some extensions for conversion specifications.
 606 (These extensions are not specified in POSIX.1-2001, but a few other
 607 systems provide similar features.)
 608 .\" HP-UX and Tru64 also have features like this.
 609 Between the \(aq%\(aq character and the conversion specifier character,
 610 an optional
 611 .I flag
 612 and field
 613 .I width
 614 may be specified.
 615 (These precede the
 616 .B E
 617 or
 618 .B O
 619 modifiers, if present.)
 620 .PP
 621 The following flag characters are permitted:
 622 .TP
 623 .B _
 624 (underscore)
 625 Pad a numeric result string with spaces.
 626 .TP
 627 .B \-
 628 (dash)
 629 Do not pad a numeric result string.
 630 .TP
 631 .B 0
 632 Pad a numeric result string with zeros even if the conversion
 633 specifier character uses space-padding by default.
 634 .TP
 635 .B \(ha
 636 Convert alphabetic characters in result string to uppercase.
 637 .TP
 638 .B #
 639 Swap the case of the result string.
 640 (This flag works only with certain conversion specifier characters,
 641 and of these, it is only really useful with
 642 .BR %Z .)
 643 .PP
 644 An optional decimal width specifier may follow the (possibly absent) flag.
 645 If the natural size of the field is smaller than this width,
 646 then the result string is padded (on the left) to the specified width.
 647 .SH BUGS
 648 If the output string would exceed
 649 .I max
 650 bytes,
 651 .I errno
 652 is
 653 .I not
 654 set.
 655 This makes it impossible to distinguish this error case from cases where the
 656 .I format
 657 string legitimately produces a zero-length output string.
 658 POSIX.1-2001
 659 does
 660 .I not
 661 specify any
 662 .I errno
 663 settings for
 664 .BR strftime ().
 665 .PP
 666 Some buggy versions of
 667 .BR gcc (1)
 668 complain about the use of
 669 .BR %c :
 670 .IR "warning: \`%c\(aq yields only last 2 digits of year in some locales" .
 671 Of course programmers are encouraged to use
 672 .BR %c ,
 673 as it gives the preferred date and time representation.
 674 One meets all kinds of strange obfuscations
 675 to circumvent this
 676 .BR gcc (1)
 677 problem.
 678 A relatively clean one is to add an
 679 intermediate function
 680 .PP
 681 .in +4n
 682 .EX
 683 size_t
 684 my_strftime(char *s, size_t max, const char *fmt,
 685             const struct tm *tm)
 686 {
 687     return strftime(s, max, fmt, tm);
 688 }
 689 .EE
 690 .in
 691 .PP
 692 Nowadays,
 693 .BR gcc (1)
 694 provides the
 695 .I \-Wno\-format\-y2k
 696 option to prevent the warning,
 697 so that the above workaround is no longer required.
 698 .SH EXAMPLES
 699 .B RFC\~2822-compliant date format
 700 (with an English locale for %a and %b)
 701 .PP
 702 .in +4n
 703 .EX
 704 "%a,\ %d\ %b\ %Y\ %T\ %z"
 705 .EE
 706 .in
 707 .PP
 708 .B RFC\~822-compliant date format
 709 (with an English locale for %a and %b)
 710 .PP
 711 .in +4n
 712 .EX
 713 "%a,\ %d\ %b\ %y\ %T\ %z"
 714 .EE
 715 .in
 716 .SS Example program
 717 The program below can be used to experiment with
 718 .BR strftime ().
 719 .PP
 720 Some examples of the result string produced by the glibc implementation of
 721 .BR strftime ()
 722 are as follows:
 723 .PP
 724 .in +4n
 725 .EX
 726 .RB "$" " ./a.out \(aq%m\(aq"
 727 Result string is "11"
 728 .RB "$" " ./a.out \(aq%5m\(aq"
 729 Result string is "00011"
 730 .RB "$" " ./a.out \(aq%_5m\(aq"
 731 Result string is "   11"
 732 .EE
 733 .in
 734 .SS Program source
 735 \&
 736 .EX
 737 #include <time.h>
 738 #include <stdio.h>
 739 #include <stdlib.h>
 740
 741 int
 742 main(int argc, char *argv[])
 743 {
 744     char outstr[200];
 745     time_t t;
 746     struct tm *tmp;
 747
 748     t = time(NULL);
 749     tmp = localtime(&t);
 750     if (tmp == NULL) {
 751         perror("localtime");
 752         exit(EXIT_FAILURE);
 753     }
 754
 755     if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
 756         fprintf(stderr, "strftime returned 0");
 757         exit(EXIT_FAILURE);
 758     }
 759
 760     printf("Result string is \e"%s\e"\en", outstr);
 761     exit(EXIT_SUCCESS);
 762 }
 763 .EE
 764 .SH SEE ALSO
 765 .BR date (1),
 766 .BR time (2),
 767 .BR ctime (3),
 768 .BR nl_langinfo (3),
 769 .BR setlocale (3),
 770 .BR sprintf (3),
 771 .BR strptime (3)