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