original/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  2014-08-19 "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 CONFORMING TO
 362 SVr4, C89, C99.
 363 There are strict inclusions between the set of conversions
 364 given in ANSI C (unmarked), those given in the Single UNIX Specification
 365 (marked SU), those given in Olson's timezone package (marked TZ),
 366 and those given in glibc (marked GNU), except that
 367 .B %+
 368 is not supported in glibc2.
 369 On the other hand glibc2 has several more extensions.
 370 POSIX.1 only refers to ANSI C; POSIX.2 describes under
 371 .BR date (1)
 372 several extensions that could apply to
 373 .BR strftime ()
 374 as well.
 375 The
 376 .B %F
 377 conversion is in C99 and POSIX.1-2001.
 378
 379 In SUSv2, the
 380 .B %S
 381 specifier allowed a range of 00 to 61,
 382 to allow for the theoretical possibility of a minute that
 383 included a double leap second
 384 (there never has been such a minute).
 385 .SH NOTES
 386 .SS ISO 8601 week dates
 387 .BR %G ,
 388 .BR %g ,
 389 and
 390 .BR %V
 391 yield values calculated from the week-based year defined by the
 392 ISO\ 8601 standard.
 393 In this system, weeks start on a Monday, and are numbered from 01,
 394 for the first week, up to 52 or 53, for the last week.
 395 Week 1 is the first week where four or more days fall within the
 396 new year (or, synonymously, week 01 is:
 397 the first week of the year that contains a Thursday;
 398 or, the week that has 4 January in it).
 399 When three of fewer days of the first calendar week of the new year fall
 400 within that year,
 401 then the ISO 8601 week-based system counts those days as part of week 53
 402 of the preceding year.
 403 For example, 1 January 2010 is a Friday,
 404 meaning that just three days of that calendar week fall in 2010.
 405 Thus, the ISO\ 8601 week-based system considers these days to be part of
 406 week 53
 407 .RB ( %V )
 408 of the year 2009
 409 .RB ( %G );
 410 week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
 411 .SS Glibc notes
 412 Glibc provides some extensions for conversion specifications.
 413 (These extensions are not specified in POSIX.1-2001, but a few other
 414 systems provide similar features.)
 415 .\" HP-UX and Tru64 also have features like this.
 416 Between the \(aq%\(aq character and the conversion specifier character,
 417 an optional
 418 .I flag
 419 and field
 420 .I width
 421 may be specified.
 422 (These precede the
 423 .B E
 424 or
 425 .B O
 426 modifiers, if present.)
 427
 428 The following flag characters are permitted:
 429 .TP
 430 .B _
 431 (underscore)
 432 Pad a numeric result string with spaces.
 433 .TP
 434 .B \-
 435 (dash)
 436 Do not pad a numeric result string.
 437 .TP
 438 .B 0
 439 Pad a numeric result string with zeros even if the conversion
 440 specifier character uses space-padding by default.
 441 .TP
 442 .B ^
 443 Convert alphabetic characters in result string to uppercase.
 444 .TP
 445 .B #
 446 Swap the case of the result string.
 447 (This flag works only with certain conversion specifier characters,
 448 and of these, it is only really useful with
 449 .BR %Z .)
 450 .PP
 451 An optional decimal width specifier may follow the (possibly absent) flag.
 452 If the natural size of the field is smaller than this width,
 453 then the result string is padded (on the left) to the specified width.
 454 .SH BUGS
 455 If the output string would exceed
 456 .I max
 457 bytes,
 458 .I errno
 459 is
 460 .I not
 461 set.
 462 This makes it impossible to distinguish this error case from cases where the
 463 .I format
 464 string legitimately produces a zero-length output string.
 465 POSIX.1-2001
 466 does
 467 .I not
 468 specify any
 469 .I errno
 470 settings for
 471 .BR strftime ().
 472
 473 Some buggy versions of
 474 .BR gcc (1)
 475 complain about the use of
 476 .BR %c :
 477 .IR "warning: `%c' yields only last 2 digits of year in some locales" .
 478 Of course programmers are encouraged to use
 479 .BR %c ,
 480 it gives the preferred date and time representation.
 481 One meets all kinds of strange obfuscations
 482 to circumvent this
 483 .BR gcc (1)
 484 problem.
 485 A relatively clean one is to add an
 486 intermediate function
 487 .in +4n
 488 .nf
 489
 490 size_t
 491 my_strftime(char *s, size_t max, const char *fmt,
 492             const struct tm *tm)
 493 {
 494     return strftime(s, max, fmt, tm);
 495 }
 496 .fi
 497 .in
 498
 499 Nowadays,
 500 .BR gcc (1)
 501 provides the
 502 .IR \-Wno\-format\-y2k
 503 option to prevent the warning,
 504 so that the above workaround is no longer required.
 505 .SH EXAMPLE
 506 .BR "RFC\ 2822-compliant date format"
 507 (with an English locale for %a and %b)
 508 .PP
 509 .in +2n
 510 "%a,\ %d\ %b\ %Y\ %T\ %z"
 511 .PP
 512 .BR "RFC\ 822-compliant date format"
 513 (with an English locale for %a and %b)
 514 .PP
 515 .in +2n
 516 "%a,\ %d\ %b\ %y\ %T\ %z"
 517 .SS Example program
 518 The program below can be used to experiment with
 519 .BR strftime ().
 520 .PP
 521 Some examples of the result string produced by the glibc implementation of
 522 .BR strftime ()
 523 are as follows:
 524 .in +4n
 525 .nf
 526
 527 .RB "$" " ./a.out \(aq%m\(aq"
 528 Result string is "11"
 529 .RB "$" " ./a.out \(aq%5m\(aq"
 530 Result string is "00011"
 531 .RB "$" " ./a.out \(aq%_5m\(aq"
 532 Result string is "   11"
 533 .fi
 534 .in
 535 .SS Program source
 536 .nf
 537 #include <time.h>
 538 #include <stdio.h>
 539 #include <stdlib.h>
 540
 541 int
 542 main(int argc, char *argv[])
 543 {
 544     char outstr[200];
 545     time_t t;
 546     struct tm *tmp;
 547
 548     t = time(NULL);
 549     tmp = localtime(&t);
 550     if (tmp == NULL) {
 551         perror("localtime");
 552         exit(EXIT_FAILURE);
 553     }
 554
 555     if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
 556         fprintf(stderr, "strftime returned 0");
 557         exit(EXIT_FAILURE);
 558     }
 559
 560     printf("Result string is \\"%s\\"\\n", outstr);
 561     exit(EXIT_SUCCESS);
 562 }
 563 .fi
 564 .SH SEE ALSO
 565 .BR date (1),
 566 .BR time (2),
 567 .BR ctime (3),
 568 .BR setlocale (3),
 569 .BR sprintf (3),
 570 .BR strptime (3)
 571 .SH COLOPHON
 572 This page is part of release 3.79 of the Linux
 573 .I man-pages
 574 project.
 575 A description of the project,
 576 information about reporting bugs,
 577 and the latest version of this page,
 578 can be found at
 579 \%http://www.kernel.org/doc/man\-pages/.