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