1 .\" 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3 .\" permission to reproduce portions of its copyrighted documentation. 4 .\" Original documentation from The Open Group can be obtained online at 5 .\" http://www.opengroup.org/bookstore/. 6 .\" 7 .\" The Institute of Electrical and Electronics Engineers and The Open 8 .\" Group, have given us permission to reprint portions of their 9 .\" documentation. 10 .\" 11 .\" In the following statement, the phrase ``this text'' refers to portions 12 .\" of the system documentation. 13 .\" 14 .\" Portions of this text are reprinted and reproduced in electronic form 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16 .\" Standard for Information Technology -- Portable Operating System 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy 20 .\" between these versions and the original IEEE and The Open Group 21 .\" Standard, the original IEEE and The Open Group Standard is the referee 22 .\" document. The original Standard can be obtained online at 23 .\" http://www.opengroup.org/unix/online.html. 24 .\" 25 .\" This notice shall appear on any product containing this material. 26 .\" 27 .\" The contents of this file are subject to the terms of the 28 .\" Common Development and Distribution License (the "License"). 29 .\" You may not use this file except in compliance with the License. 30 .\" 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32 .\" or http://www.opensolaris.org/os/licensing. 33 .\" See the License for the specific language governing permissions 34 .\" and limitations under the License. 35 .\" 36 .\" When distributing Covered Code, include this CDDL HEADER in each 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38 .\" If applicable, add the following below this CDDL HEADER, with the 39 .\" fields enclosed by brackets "[]" replaced with your own identifying 40 .\" information: Portions Copyright [yyyy] [name of copyright owner] 41 .\" 42 .\" 43 .\" Copyright 1989 AT&T 44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. 45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. 46 .\" Copyright (c) 2014 Gary Mills 47 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org> 48 .\" 49 .TH STRFTIME 3C "Mar 30, 2019" 50 .SH NAME 51 strftime, strftime_l cftime, ascftime \- convert date and time to string 52 .SH SYNOPSIS 53 .LP 54 .nf 55 #include <time.h> 56 57 \fBsize_t\fR \fBstrftime\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fImaxsize\fR, 58 \fBconst char *restrict\fR \fIformat\fR, 59 \fBconst struct tm *restrict\fR \fItimeptr\fR); 60 .fi 61 .LP 62 .nf 63 \fBsize_t\fR \fBstrftime_l\fR(\fBchar *restrict\fR \fIs\fR, \fBsize_t\fR \fImaxsize\fR, 64 \fBconst char *restrict\fR \fIformat\fR, 65 \fBconst struct tm *restrict\fR \fItimeptr\fR, \fBlocale_t\fR \fIloc\fR); 66 .fi 67 .LP 68 .nf 69 \fBint\fR \fBcftime\fR(\fBchar *\fR\fIs\fR, \fBchar *\fR\fIformat\fR, \fBconst time_t *\fR\fIclock\fR); 70 .fi 71 .LP 72 .nf 73 \fBint\fR \fBascftime\fR(\fBchar *\fR\fIs\fR, \fBconst char *\fR\fIformat\fR, 74 \fBconst struct tm *\fR\fItimeptr\fR); 75 .fi 76 77 .SH DESCRIPTION 78 .LP 79 The \fBstrftime()\fR, \fBstrftime_l()\fR, \fBascftime()\fR, and \fBcftime()\fR 80 functions place 81 bytes into the array pointed to by \fIs\fR as controlled by the string pointed 82 to by \fIformat\fR. The \fIformat\fR string consists of zero or more conversion 83 specifications and ordinary characters. A conversion specification consists of 84 a '\fB%\fR' (percent) character and one or two terminating conversion 85 characters that determine the conversion specification's behavior. All 86 ordinary characters (including the terminating null byte) are copied unchanged 87 into the array pointed to by \fIs\fR. If copying takes place between objects 88 that overlap, the behavior is undefined. For \fBstrftime()\fR, no more than 89 \fImaxsize\fR bytes are placed into the array. The \fBstrftime_l()\fR function 90 behaves identically to \fBstrftime()\fR function, but instead of operating in 91 the current locale, it operates in the locale specified by \fIloc\fR. 92 .LP 93 If \fIformat\fR is \fBNULL\fR, then the locale's default format is used. 94 For \fBstrftime()\fR the default format is the same as \fB%c\fR; for 95 \fBcftime()\fR and \fBascftime()\fR the default format is the same as \fB%+\fR. 96 \fBcftime()\fR and \fBascftime()\fR first try to use the value of the 97 environment variable \fBCFTIME\fR, and if that is undefined or empty, the 98 default format is used. 99 .LP 100 Each conversion specification is replaced by appropriate characters as 101 described in the following list. The appropriate characters are determined by 102 the \fBLC_TIME\fR category of the program's locale and by the values contained 103 in the structure pointed to by \fItimeptr\fR for \fBstrftime()\fR and 104 \fBascftime()\fR, and by the time represented by \fIclock\fR for 105 \fBcftime()\fR. 106 .sp 107 .ne 2 108 .na 109 \fB\fB%%\fR\fR 110 .ad 111 .RS 6n 112 Same as \fB%\fR. 113 .RE 114 115 .sp 116 .ne 2 117 .na 118 \fB\fB%a\fR\fR 119 .ad 120 .RS 6n 121 Locale's abbreviated weekday name. 122 .RE 123 124 .sp 125 .ne 2 126 .na 127 \fB\fB%A\fR\fR 128 .ad 129 .RS 6n 130 Locale's full weekday name. 131 .RE 132 133 .sp 134 .ne 2 135 .na 136 \fB\fB%b\fR\fR 137 .ad 138 .RS 6n 139 Locale's abbreviated month name. 140 .RE 141 142 .sp 143 .ne 2 144 .na 145 \fB\fB%B\fR\fR 146 .ad 147 .RS 6n 148 Locale's full month name. 149 .RE 150 151 .sp 152 .ne 2 153 .na 154 \fB\fB%c\fR\fR 155 .ad 156 .RS 6n 157 Locale's appropriate date and time representation. 158 In the C locale, this format is: 159 .sp 160 .in +2 161 .nf 162 %a %b %e %H:%M:%S %Y 163 .fi 164 .in -2 165 .sp 166 Other locales may have different locale-specific formats. 167 .RE 168 169 .sp 170 .ne 2 171 .na 172 \fB\fB%C\fR\fR 173 .ad 174 .RS 6n 175 Century number (the year divided by 100 and truncated to an integer as a 176 decimal number [01,99]). 177 .RE 178 179 .sp 180 .ne 2 181 .na 182 \fB\fB%d\fR\fR 183 .ad 184 .RS 6n 185 Day of month [01,31]. 186 .RE 187 188 .sp 189 .ne 2 190 .na 191 \fB\fB%D\fR\fR 192 .ad 193 .RS 6n 194 Date as \fB%m\fR/\fB%d\fR/\fB%y\fR. 195 .RE 196 197 .sp 198 .ne 2 199 .na 200 \fB\fB%e\fR\fR 201 .ad 202 .RS 6n 203 Day of month [1,31]; single digits are preceded by a space. 204 .RE 205 206 .sp 207 .ne 2 208 .na 209 \fB\fB%F\fR\fR 210 .ad 211 .RS 6n 212 Equivalent to \fB%Y\fR-\fB%m\fR-\fB%d\fR (the ISO 8601:2000 standard date 213 format). 214 .RE 215 216 .sp 217 .ne 2 218 .na 219 \fB\fB%g\fR\fR 220 .ad 221 .RS 6n 222 Week-based year within century [00,99]. 223 .RE 224 225 .sp 226 .ne 2 227 .na 228 \fB\fB%G\fR\fR 229 .ad 230 .RS 6n 231 Week-based year, including the century [0000,9999]. 232 .RE 233 234 .sp 235 .ne 2 236 .na 237 \fB\fB%h\fR\fR 238 .ad 239 .RS 6n 240 Locale's abbreviated month name. 241 .RE 242 243 .sp 244 .ne 2 245 .na 246 \fB\fB%H\fR\fR 247 .ad 248 .RS 6n 249 Hour (24-hour clock) [00,23]. 250 .RE 251 252 .sp 253 .ne 2 254 .na 255 \fB\fB%I\fR\fR 256 .ad 257 .RS 6n 258 Hour (12-hour clock) [01,12]. 259 .RE 260 261 .sp 262 .ne 2 263 .na 264 \fB\fB%j\fR\fR 265 .ad 266 .RS 6n 267 Day number of year [001,366]. 268 .RE 269 270 .sp 271 .ne 2 272 .na 273 \fB\fB%k\fR\fR 274 .ad 275 .RS 6n 276 Hour (24-hour clock) [0,23]; single digits are preceded by a space. 277 .RE 278 279 .sp 280 .ne 2 281 .na 282 \fB\fB%l\fR\fR 283 .ad 284 .RS 6n 285 Hour (12-hour clock) [1,12]; single digits are preceded by a space. 286 .RE 287 288 .sp 289 .ne 2 290 .na 291 \fB\fB%m\fR\fR 292 .ad 293 .RS 6n 294 Month number [01,12]. 295 .RE 296 297 .sp 298 .ne 2 299 .na 300 \fB\fB%M\fR\fR 301 .ad 302 .RS 6n 303 Minute [00,59]. 304 .RE 305 306 .sp 307 .ne 2 308 .na 309 \fB\fB%n\fR\fR 310 .ad 311 .RS 6n 312 Insert a NEWLINE. 313 .RE 314 315 .sp 316 .ne 2 317 .na 318 \fB\fB%p\fR\fR 319 .ad 320 .RS 6n 321 Locale's equivalent of either a.m. or p.m. 322 .RE 323 324 .sp 325 .ne 2 326 .na 327 \fB\fB%r\fR\fR 328 .ad 329 .RS 6n 330 Appropriate time representation in 12-hour clock format with \fB%p\fR. 331 .RE 332 333 .sp 334 .ne 2 335 .na 336 \fB\fB%R\fR\fR 337 .ad 338 .RS 6n 339 Time as \fB%H\fR:\fB%M\fR. 340 .RE 341 342 .sp 343 .ne 2 344 .na 345 \fB\fB%s\fR\fR 346 .ad 347 .RS 6n 348 Seconds since 00:00:00 UTC, January 1, 1970. 349 .RE 350 351 .sp 352 .ne 2 353 .na 354 \fB\fB%S\fR\fR 355 .ad 356 .RS 6n 357 Seconds [00,60]; the range of values is [00,60] rather than [00,59] to allow 358 for the occasional leap second. 359 .RE 360 361 .sp 362 .ne 2 363 .na 364 \fB\fB%t\fR\fR 365 .ad 366 .RS 6n 367 Insert a TAB. 368 .RE 369 370 .sp 371 .ne 2 372 .na 373 \fB\fB%T\fR\fR 374 .ad 375 .RS 6n 376 Time as \fB%H\fR:\fB%M\fR:\fB%S\fR. 377 .RE 378 379 .sp 380 .ne 2 381 .na 382 \fB\fB%u\fR\fR 383 .ad 384 .RS 6n 385 Weekday as a decimal number [1,7], with 1 representing Monday. See \fBNOTES\fR 386 below. 387 .RE 388 389 .sp 390 .ne 2 391 .na 392 \fB\fB%U\fR\fR 393 .ad 394 .RS 6n 395 Week number of year as a decimal number [00,53], with Sunday as the first day 396 of week 1. 397 .RE 398 399 .sp 400 .ne 2 401 .na 402 \fB\fB%v\fR\fR 403 .ad 404 .RS 6n 405 Date as \fB%e\fR-\fB%b\fR-\fB%Y\fR. 406 .RE 407 408 .sp 409 .ne 2 410 .na 411 \fB\fB%V\fR\fR 412 .ad 413 .RS 6n 414 The ISO 8601 week number as a decimal number [01,53]. In the ISO 8601 415 week-based system, weeks begin on a Monday and week 1 of the year is the week 416 that includes both January 4th and the first Thursday of the year. If the 417 first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of 418 the last week of the preceding year. See \fBNOTES\fR below. 419 .RE 420 421 .sp 422 .ne 2 423 .na 424 \fB\fB%w\fR\fR 425 .ad 426 .RS 6n 427 Weekday as a decimal number [0,6], with 0 representing Sunday. 428 .RE 429 430 .sp 431 .ne 2 432 .na 433 \fB\fB%W\fR\fR 434 .ad 435 .RS 6n 436 Week number of year as a decimal number [00,53], with Monday as the first day 437 of week 1. 438 .RE 439 440 .sp 441 .ne 2 442 .na 443 \fB\fB%x\fR\fR 444 .ad 445 .RS 6n 446 Locale's appropriate date representation. 447 .RE 448 449 .sp 450 .ne 2 451 .na 452 \fB\fB%X\fR\fR 453 .ad 454 .RS 6n 455 Locale's appropriate time representation. 456 .RE 457 458 .sp 459 .ne 2 460 .na 461 \fB\fB%y\fR\fR 462 .ad 463 .RS 6n 464 Year within century [00,99]. 465 .RE 466 467 .sp 468 .ne 2 469 .na 470 \fB\fB%Y\fR\fR 471 .ad 472 .RS 6n 473 Year, including the century (for example 1993). 474 .RE 475 476 .sp 477 .ne 2 478 .na 479 \fB\fB%z\fR\fR 480 .ad 481 .RS 6n 482 Replaced by offset from UTC in ISO 8601:2000 standard format (\fB+hhmm\fR or 483 \fB-hhmm\fR), or by no characters if no time zone is determinable. For example, 484 "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich). If 485 \fBtm_isdst\fR is zero, the standard time offset is used. If \fBtm_isdst\fR is 486 greater than zero, the daylight savings time offset if used. If \fBtm_isdst\fR 487 is negative, no characters are returned. 488 .RE 489 490 .sp 491 .ne 2 492 .na 493 \fB\fB%Z\fR\fR 494 .ad 495 .RS 6n 496 Time zone name or abbreviation, or no bytes if no time zone information exists. 497 .RE 498 499 .sp 500 .ne 2 501 .na 502 \fB\fB%+\fR\fR 503 .ad 504 .RS 6n 505 Locale's date and time representation as produced by \fBdate\fR(1). 506 .RE 507 508 .LP 509 If a conversion specification does not correspond to any of the above or to any 510 of the modified conversion specifications listed below, the behavior is 511 undefined and \fB0\fR is returned. 512 .LP 513 The difference between \fB%U\fR and \fB%W\fR (and also between modified 514 conversion specifications \fB%OU\fR and \fB%OW\fR) lies in which day is counted 515 as the first of the week. Week number 1 is the first week in January starting 516 with a Sunday for \fB%U\fR or a Monday for \fB%W\fR. Week number 0 contains 517 those days before the first Sunday or Monday in January for \fB%U\fR and 518 \fB%W\fR, respectively. 519 .SS "Modified Conversion Specifications" 520 .LP 521 Some conversion specifications can be modified by the \fBE\fR and \fBO\fR 522 modifiers to indicate that an alternate format or specification should be used 523 rather than the one normally used by the unmodified conversion specification. 524 If the alternate format or specification does not exist in the current locale, 525 the behavior will be as if the unmodified specification were used. 526 .sp 527 .ne 2 528 .na 529 \fB\fB%Ec\fR\fR 530 .ad 531 .RS 7n 532 Locale's alternate appropriate date and time representation. 533 .RE 534 535 .sp 536 .ne 2 537 .na 538 \fB\fB%EC\fR\fR 539 .ad 540 .RS 7n 541 Name of the base year (period) in the locale's alternate representation. 542 .RE 543 544 .sp 545 .ne 2 546 .na 547 \fB\fB%Eg\fR\fR 548 .ad 549 .RS 7n 550 Offset from \fB%EC\fR of the week-based year in the locale's alternative 551 representation. 552 .RE 553 554 .sp 555 .ne 2 556 .na 557 \fB\fB%EG\fR\fR 558 .ad 559 .RS 7n 560 Full alternative representation of the week-based year. 561 .RE 562 563 .sp 564 .ne 2 565 .na 566 \fB\fB%Ex\fR\fR 567 .ad 568 .RS 7n 569 Locale's alternate date representation. 570 .RE 571 572 .sp 573 .ne 2 574 .na 575 \fB\fB%EX\fR\fR 576 .ad 577 .RS 7n 578 Locale's alternate time representation. 579 .RE 580 581 .sp 582 .ne 2 583 .na 584 \fB\fB%Ey\fR\fR 585 .ad 586 .RS 7n 587 Offset from \fB%EC\fR (year only) in the locale's alternate representation. 588 .RE 589 590 .sp 591 .ne 2 592 .na 593 \fB\fB%EY\fR\fR 594 .ad 595 .RS 7n 596 Full alternate year representation. 597 .RE 598 599 .sp 600 .ne 2 601 .na 602 \fB\fB%Od\fR\fR 603 .ad 604 .RS 7n 605 Day of the month using the locale's alternate numeric symbols. 606 .RE 607 608 .sp 609 .ne 2 610 .na 611 \fB\fB%Oe\fR\fR 612 .ad 613 .RS 7n 614 Same as \fB%Od\fR. 615 .RE 616 617 .sp 618 .ne 2 619 .na 620 \fB\fB%Og\fR\fR 621 .ad 622 .RS 7n 623 Week-based year (offset from \fB%C\fR) in the locale's alternate representation 624 and using the locale's alternate numeric symbols. 625 .RE 626 627 .sp 628 .ne 2 629 .na 630 \fB\fB%OH\fR\fR 631 .ad 632 .RS 7n 633 Hour (24-hour clock) using the locale's alternate numeric symbols. 634 .RE 635 636 .sp 637 .ne 2 638 .na 639 \fB\fB%OI\fR\fR 640 .ad 641 .RS 7n 642 Hour (12-hour clock) using the locale's alternate numeric symbols. 643 .RE 644 645 .sp 646 .ne 2 647 .na 648 \fB\fB%Om\fR\fR 649 .ad 650 .RS 7n 651 Month using the locale's alternate numeric symbols. 652 .RE 653 654 .sp 655 .ne 2 656 .na 657 \fB\fB%OM\fR\fR 658 .ad 659 .RS 7n 660 Minutes using the locale's alternate numeric symbols. 661 .RE 662 663 .sp 664 .ne 2 665 .na 666 \fB\fB%OS\fR\fR 667 .ad 668 .RS 7n 669 Seconds using the locale's alternate numeric symbols. 670 .RE 671 672 .sp 673 .ne 2 674 .na 675 \fB\fB%Ou\fR\fR 676 .ad 677 .RS 7n 678 Weekday as a number in the locale's alternate numeric symbols. 679 .RE 680 681 .sp 682 .ne 2 683 .na 684 \fB\fB%OU\fR\fR 685 .ad 686 .RS 7n 687 Week number of the year (Sunday as the first day of the week) using the 688 locale's alternate numeric symbols. 689 .RE 690 691 .sp 692 .ne 2 693 .na 694 \fB\fB%Ow\fR\fR 695 .ad 696 .RS 7n 697 Number of the weekday (Sunday=0) using the locale's alternate numeric symbols. 698 .RE 699 700 .sp 701 .ne 2 702 .na 703 \fB\fB%OW\fR\fR 704 .ad 705 .RS 7n 706 Week number of the year (Monday as the first day of the week) using the 707 locale's alternate numeric symbols. 708 .RE 709 710 .sp 711 .ne 2 712 .na 713 \fB\fB%Oy\fR\fR 714 .ad 715 .RS 7n 716 Year (offset from \fB%C\fR) in the locale's alternate representation and using 717 the locale's alternate numeric symbols. 718 .RE 719 720 .SS "Selecting the Output Language" 721 .LP 722 These routines produce output that is formatted according to the \fBLC_TIME\fR 723 locale category. They use either the current locale, or in the case of 724 \fBstrftime_l()\fR, the locale supplied by \fIloc\fR. 725 .SS "Time Zone" 726 .LP 727 Local time zone information is used as though \fBtzset\fR(3C) were called. 728 .SH RETURN VALUES 729 .LP 730 These functions return the 731 number of characters placed into the array pointed to by \fIs\fR, not including 732 the terminating null character. If the total number of resulting characters 733 including the terminating null character is more than \fImaxsize\fR, 734 \fBstrftime()\fR returns \fB0\fR and the contents of the array are 735 indeterminate. 736 .SH EXAMPLES 737 .LP 738 \fBExample 1 \fRAn example of the \fBstrftime()\fR function. 739 .LP 740 The following example illustrates the use of \fBstrftime()\fR for the 741 \fBPOSIX\fR locale. It shows what the string in \fIstr\fR would look like if 742 the structure pointed to by \fItmptr\fR contains the values corresponding to 743 Thursday, August 28, 1986 at 12:44:36. 744 .nf 745 .IP 746 \fBstrftime\fR(\fIstr\fR, \fIstrsize\fR, "%A %b %d %j", \fItmptr\fR); 747 .fi 748 .LP 749 This results in \fIstr\fR containing "Thursday Aug 28 240". 750 .SH ATTRIBUTES 751 .LP 752 See \fBattributes\fR(5) for descriptions of the following attributes: 753 .TS 754 box; 755 c | c 756 l | l . 757 ATTRIBUTE TYPE ATTRIBUTE VALUE 758 _ 759 CSI Enabled 760 _ 761 Interface Stability See below. 762 _ 763 MT-Level MT-Safe 764 _ 765 Standard See below. 766 .TE 767 768 .LP 769 The \fBstrftime()\fR and \fBstrftime_l()\fR functions are Standard. 770 \fBcftime()\fR and \fBascftime()\fR functions are Committed. 771 .LP 772 For \fBstrftime()\fR and \fBstrftime_l()\fR, see \fBstandards\fR(5). 773 .SH SEE ALSO 774 .LP 775 \fBdate\fR(1), \fBctime\fR(3C), \fBmktime\fR(3C), 776 \fBnewlocale\fR(3C), \fBsetlocale\fR(3C), \fBstrptime\fR(3C), \fBtzset\fR(3C), 777 \fBuselocale\fR(3C), \fBTIMEZONE\fR(4), \fBzoneinfo\fR(4), 778 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5) 779 .SH NOTES 780 .LP 781 The conversion specification for \fB%V\fR was changed in the Solaris 7 release. 782 This change was based on the public review draft of the ISO C9x standard at 783 that time. Previously, the specification stated that if the week containing 1 784 January had fewer than four days in the new year, it became week 53 of the 785 previous year. The ISO C9x standard committee subsequently recognized that that 786 specification had been incorrect. 787 .LP 788 The conversion specifications for \fB%g\fR, \fB%G\fR, \fB%Eg\fR, \fB%EG\fR, and 789 \fB%Og\fR were added in the Solaris 7 release. This change was based on the 790 public review draft of the ISO C9x standard at that time. The \fB%g\fR and 791 \fB%G\fR specifications were adopted in the formal standard. The other two 792 were not, and should not be used in portable applications. 793 .LP 794 The conversion specification for \fB%u\fR was changed in the Solaris 8 release. 795 This change was based on the XPG4 specification. 796 .LP 797 If using the \fB%Z\fR specifier and \fBzoneinfo\fR timezones and if the input 798 date is outside the range 20:45:52 UTC, December 13, 1901 to 03:14:07 UTC, 799 January 19, 2038, the timezone name may not be correct. 800 .LP 801 The conversion specification for \fB%+\fR was added in illumos. 802 It is not part of any standard, although it is available on a number 803 of other platforms. 804 Its use is discouraged for conforming applications.