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