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
|
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
|