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