| blob | 6d889e9fc11b624aa295c42ed501694274bd91c5 |
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 (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
45 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
46 .\"
47 .TH STRPTIME 3C "Jun 27, 2014"
48 .SH NAME
49 strptime, strptime_l \- date and time conversion
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <time.h>
55 \fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR,
56 \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR);
57 .fi
58 .LP
59 .nf
60 #include <time.h>
61 #include <xlocale.h>
63 \fBchar *\fR\fBstrptime_l\fR(\fBconst char *restrict\fR \fIbuf\fR,
64 \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR,
65 \fBlocale_t\fR \fIloc\fR);
66 .fi
67 .SS "Non-zeroing Behavior"
68 .LP
69 .nf
70 \fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-D_STRPTIME_DONTZERO\fR [\fIlibrary\fR...]
71 #include <time.h>
73 \fBchar *\fR\fBstrptime\fR(\fBconst char *restrict\fR \fIbuf\fR,
74 \fBconst char *restrict\fR \fIformat\fR, \fBstruct tm *restrict\fR \fItm\fR);
75 .fi
77 .SH DESCRIPTION
78 .LP
79 The \fBstrptime()\fR function converts the character string pointed to by
80 \fIbuf\fR to values which are stored in the \fBtm\fR structure pointed to by
81 \fItm\fR, using the format specified by \fIformat\fR. The \fBstrptime_l()\fR
82 function is identical to \fBstrptime()\fR except instead of acting in the
83 current locale, it acts in the locale specified by the argument \fIloc\fR.
84 .LP
85 The \fIformat\fR argument is composed of zero or more conversion
86 specifications. Each conversion specification is composed of a "%" (percent)
87 character followed by one or two conversion characters which specify the
88 replacement required. One or more white space characters (as specified by
89 \fBisspace\fR(3C)) may precede or follow a conversion specification. There must
90 be white-space or other non-alphanumeric characters between any two conversion
91 specifications.
92 .LP
93 A non-zeroing version of \fBstrptime()\fR, described below under \fBNon-zeroing
94 Behavior\fR, is provided if \fB_STRPTIME_DONTZERO\fR is defined.
95 .SS "Conversion Specifications"
96 .LP
97 The following conversion specifications are supported:
98 .sp
99 .ne 2
100 .na
101 \fB\fB%%\fR\fR
102 .ad
103 .RS 6n
104 Same as \fB%\fR.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fB%a\fR\fR
111 .ad
112 .RS 6n
113 Day of week, using the locale's weekday names; either the abbreviated or full
114 name may be specified.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fB%A\fR\fR
121 .ad
122 .RS 6n
123 Same as \fB%a\fR.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fB%b\fR\fR
130 .ad
131 .RS 6n
132 Month, using the locale's month names; either the abbreviated or full name may
133 be specified.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fB%B\fR\fR
140 .ad
141 .RS 6n
142 Same as \fB%b\fR.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fB%c\fR\fR
149 .ad
150 .RS 6n
151 Locale's appropriate date and time representation.
152 .RE
154 .sp
155 .ne 2
156 .na
157 \fB\fB%C\fR\fR
158 .ad
159 .RS 6n
160 Century number (the year divided by 100 and truncated to an integer as a
161 decimal number [1,99]); single digits are preceded by 0. If \fB%C\fR is used
162 without the \fB%y\fR specifier, \fBstrptime()\fR assumes the year offset is
163 zero in whichever century is specified. Note the behavior of \fB%C\fR in the
164 absence of \fB%y\fR is not specified by any of the standards or specifications
165 described on the \fBstandards\fR(5) manual page, so portable applications
166 should not depend on it. This behavior may change in a future release.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fB%d\fR\fR
173 .ad
174 .RS 6n
175 Day of month [1,31]; leading zero is permitted but not required.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fB%D\fR\fR
182 .ad
183 .RS 6n
184 Date as \fB%m\fR/\fB%d\fR/\fB%y\fR.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fB%e\fR\fR
191 .ad
192 .RS 6n
193 Same as \fB%d\fR.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fB%h\fR\fR
200 .ad
201 .RS 6n
202 Same as \fB%b\fR.
203 .RE
205 .sp
206 .ne 2
207 .na
208 \fB\fB%H\fR\fR
209 .ad
210 .RS 6n
211 Hour (24-hour clock) [0,23]; leading zero is permitted but not required.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fB%I\fR\fR
218 .ad
219 .RS 6n
220 Hour (12-hour clock) [1,12]; leading zero is permitted but not required.
221 .RE
223 .sp
224 .ne 2
225 .na
226 \fB\fB%j\fR\fR
227 .ad
228 .RS 6n
229 Day number of the year [1,366]; leading zeros are permitted but not required.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fB%m\fR\fR
236 .ad
237 .RS 6n
238 Month number [1,12]; leading zero is permitted but not required.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fB%M\fR\fR
245 .ad
246 .RS 6n
247 Minute [0-59]; leading zero is permitted but not required.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fB%n\fR\fR
254 .ad
255 .RS 6n
256 Any white space.
257 .RE
259 .sp
260 .ne 2
261 .na
262 \fB\fB%p\fR\fR
263 .ad
264 .RS 6n
265 Locale's equivalent of either a.m. or p.m.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fB%r\fR\fR
272 .ad
273 .RS 6n
274 Appropriate time representation in the 12-hour clock format with \fB%p\fR.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fB%R\fR\fR
281 .ad
282 .RS 6n
283 Time as \fB%H\fR:\fB%M\fR.
284 .RE
286 .SS "SUSv3"
287 .sp
288 .ne 2
289 .na
290 \fB\fB%S\fR\fR
291 .ad
292 .RS 6n
293 Seconds [0,60]; leading zero is permitted but not required. The range of values
294 is [00,60] rather than [00,59] to allow for the occasional leap second.
295 .RE
297 .SS "Default and other standards"
298 .sp
299 .ne 2
300 .na
301 \fB\fB%S\fR\fR
302 .ad
303 .RS 6n
304 Seconds [0,61]; leading zero is permitted but not required. The range of values
305 is [00,61] rather than [00,59] to allow for the occasional leap second and even
306 more occasional double leap second.
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fB%t\fR\fR
313 .ad
314 .RS 6n
315 Any white space.
316 .RE
318 .sp
319 .ne 2
320 .na
321 \fB\fB%T\fR\fR
322 .ad
323 .RS 6n
324 Time as \fB%H\fR:\fB%M\fR:\fB%S\fR.
325 .RE
327 .sp
328 .ne 2
329 .na
330 \fB\fB%U\fR\fR
331 .ad
332 .RS 6n
333 Week number of the year as a decimal number [0,53], with Sunday as the first
334 day of the week; leading zero is permitted but not required.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fB%w\fR\fR
341 .ad
342 .RS 6n
343 Weekday as a decimal number [0,6], with 0 representing Sunday.
344 .RE
346 .sp
347 .ne 2
348 .na
349 \fB\fB%W\fR\fR
350 .ad
351 .RS 6n
352 Week number of the year as a decimal number [0,53], with Monday as the first
353 day of the week; leading zero is permitted but not required.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fB%x\fR\fR
360 .ad
361 .RS 6n
362 Locale's appropriate date representation.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fB%X\fR\fR
369 .ad
370 .RS 6n
371 Locale's appropriate time representation.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fB%y\fR\fR
378 .ad
379 .RS 6n
380 Year within century. When a century is not otherwise specified, values in the
381 range 69-99 refer to years in the twentieth century (1969 to 1999 inclusive);
382 values in the range 00-68 refer to years in the twenty-first century (2000 to
383 2068 inclusive).
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fB%Y\fR\fR
390 .ad
391 .RS 6n
392 Year, including the century (for example, 1993).
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fB%Z\fR\fR
399 .ad
400 .RS 6n
401 Time zone name or no characters if no time zone exists.
402 .RE
404 .SS "Modified Conversion Specifications"
405 .LP
406 Some conversion specifications can be modified by the \fBE\fR and \fBO\fR
407 modifier characters to indicate that an alternate format or specification
408 should be used rather than the one normally used by the unmodified
409 specification. If the alternate format or specification does not exist in the
410 current locale, the behavior will be as if the unmodified conversion
411 specification were used.
412 .sp
413 .ne 2
414 .na
415 \fB\fB%Ec\fR\fR
416 .ad
417 .RS 7n
418 Locale's alternate appropriate date and time representation.
419 .RE
421 .sp
422 .ne 2
423 .na
424 \fB\fB%EC\fR\fR
425 .ad
426 .RS 7n
427 Name of the base year (era) in the locale's alternate representation.
428 .RE
430 .sp
431 .ne 2
432 .na
433 \fB\fB%Ex\fR\fR
434 .ad
435 .RS 7n
436 Locale's alternate date representation.
437 .RE
439 .sp
440 .ne 2
441 .na
442 \fB\fB%EX\fR\fR
443 .ad
444 .RS 7n
445 Locale's alternate time representation.
446 .RE
448 .sp
449 .ne 2
450 .na
451 \fB\fB%Ey\fR\fR
452 .ad
453 .RS 7n
454 Offset from \fB%EC\fR (year only) in the locale's alternate representation.
455 .RE
457 .sp
458 .ne 2
459 .na
460 \fB\fB%EY\fR\fR
461 .ad
462 .RS 7n
463 Full alternate year representation.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB\fB%Od\fR\fR
470 .ad
471 .RS 7n
472 Day of the month using the locale's alternate numeric symbols.
473 .RE
475 .sp
476 .ne 2
477 .na
478 \fB\fB%Oe\fR\fR
479 .ad
480 .RS 7n
481 Same as \fB%Od\fR.
482 .RE
484 .sp
485 .ne 2
486 .na
487 \fB\fB%OH\fR\fR
488 .ad
489 .RS 7n
490 Hour (24-hour clock) using the locale's alternate numeric symbols.
491 .RE
493 .sp
494 .ne 2
495 .na
496 \fB\fB%OI\fR\fR
497 .ad
498 .RS 7n
499 Hour (12-hour clock) using the locale's alternate numeric symbols.
500 .RE
502 .sp
503 .ne 2
504 .na
505 \fB\fB%Om\fR\fR
506 .ad
507 .RS 7n
508 Month using the locale's alternate numeric symbols.
509 .RE
511 .sp
512 .ne 2
513 .na
514 \fB\fB%OM\fR\fR
515 .ad
516 .RS 7n
517 Minutes using the locale's alternate numeric symbols.
518 .RE
520 .sp
521 .ne 2
522 .na
523 \fB\fB%OS\fR\fR
524 .ad
525 .RS 7n
526 Seconds using the locale's alternate numeric symbols.
527 .RE
529 .sp
530 .ne 2
531 .na
532 \fB\fB%OU\fR\fR
533 .ad
534 .RS 7n
535 Week number of the year (Sunday as the first day of the week) using the
536 locale's alternate numeric symbols.
537 .RE
539 .sp
540 .ne 2
541 .na
542 \fB\fB%Ow\fR\fR
543 .ad
544 .RS 7n
545 Number of the weekday (Sunday=0) using the locale's alternate numeric symbols.
546 .RE
548 .sp
549 .ne 2
550 .na
551 \fB\fB%OW\fR\fR
552 .ad
553 .RS 7n
554 Week number of the year (Monday as the first day of the week) using the
555 locale's alternate numeric symbols.
556 .RE
558 .sp
559 .ne 2
560 .na
561 \fB\fB%Oy\fR\fR
562 .ad
563 .RS 7n
564 Year (offset from \fB%C\fR) in the locale's alternate representation and using
565 the locale's alternate numeric symbols.
566 .RE
568 .SS "General Specifications"
569 .LP
570 A conversion specification that is an ordinary character is executed by
571 scanning the next character from the buffer. If the character scanned from the
572 buffer differs from the one comprising the specification, the specification
573 fails, and the differing and subsequent characters remain unscanned.
574 .sp
575 .LP
576 A series of specifications composed of \fB%n\fR, \fB%t\fR, white-space
577 characters or any combination is executed by scanning up to the first character
578 that is not white space (which remains unscanned), or until no more characters
579 can be scanned. White space is defined by \fBisspace\fR(3C).
580 .LP
581 Any other conversion specification is executed by scanning characters until a
582 character matching the next specification is scanned, or until no more
583 characters can be scanned. These characters, except the one matching the next
584 specification, are then compared to the locale values associated with the
585 conversion specifier. If a match is found, values for the appropriate
586 \fItm\fR structure members are set to values corresponding to the locale
587 information. If no match is found, \fBstrptime()\fR fails and no more
588 characters are scanned.
589 .sp
590 .LP
591 The month names, weekday names, era names, and alternate numeric symbols can
592 consist of any combination of upper and lower case letters. The user can
593 request that the input date or time specification be in a specific language by
594 setting the \fBLC_TIME\fR category using \fBsetlocale\fR(3C).
595 .SS "Non-zeroing Behavior"
596 .LP
597 In addition to the behavior described above by various standards, the Solaris
598 implementation of \fBstrptime()\fR provides the following extensions. These may
599 change at any time in the future. Portable applications should not depend on
600 these extended features:
601 .RS +4
602 .TP
603 .ie t \(bu
604 .el o
605 If \fB_STRPTIME_DONTZERO\fR is not defined, the \fBtm struct\fR is zeroed on
606 entry and \fBstrptime()\fR updates the fields of the \fBtm struct\fR associated
607 with the specifiers in the format string.
608 .RE
609 .RS +4
610 .TP
611 .ie t \(bu
612 .el o
613 If \fB_STRPTIME_DONTZERO\fR is defined, \fBstrptime()\fR does not zero the
614 \fBtm struct\fR on entry. Additionally, for some specifiers, \fBstrptime()\fR
615 will use some values in the input \fBtm struct\fR to recalculate the date and
616 re-assign the appropriate members of the \fBtm struct\fR.
617 .RE
618 .LP
619 The following describes extended features regardless of whether
620 \fB_STRPTIME_DONTZERO\fR is defined or not defined:
621 .RS +4
622 .TP
623 .ie t \(bu
624 .el o
625 If \fB%j\fR is specified, \fBtm_yday\fR is set; if year is given, and if month
626 and day are not given, \fBstrptime()\fR calculates and sets \fBtm_mon\fR,
627 \fBtm_mday\fR, and \fBtm_year\fR.
628 .RE
629 .RS +4
630 .TP
631 .ie t \(bu
632 .el o
633 If \fB%U\fR or \fB%W\fR is specified and if weekday and year are given and
634 month and day of month are not given, \fBstrptime()\fR calculates and sets
635 \fBtm_mon\fR, \fBtm_mday\fR, \fBtm_wday\fR, and \fBtm_year\fR.
636 .RE
637 .LP
638 The following describes extended features when \fB_STRPTIME_DONTZERO\fR is not
639 defined:
640 .RS +4
641 .TP
642 .ie t \(bu
643 .el o
644 If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fRassumes
645 0 as the year offset, then calculates the year, and assigns \fBtm_year\fR.
646 .RE
647 .LP
648 The following describes extended features when \fB_STRPTIME_DONTZERO\fR is
649 defined:
650 .RS +4
651 .TP
652 .ie t \(bu
653 .el o
654 If \fB%C\fR is specified and \fB%y\fR is not specified, \fBstrptime()\fR
655 assumes the year offset of the year value of the \fBtm_year\fR member of the
656 input \fBtm struct\fR, then calculates the year and assigns \fBtm_year\fR.
657 .RE
658 .RS +4
659 .TP
660 .ie t \(bu
661 .el o
662 If \fB%j\fR is specified and neither \fB%y\fR, \fB%Y\fR, nor \fB%C\fR are
663 specified, and neither month nor day of month are specified, \fBstrptime()\fR
664 assumes the year value given by the value of the \fBtm_year\fR field of the
665 input \fBtm struct\fR. Then, in addition to setting \fBtm_yday\fR,
666 \fBstrptime()\fR uses day-of-year and year values to calculate the month and
667 day-of-month, and assigns \fBtm_month\fR and \fBtm_mday\fR.
668 .RE
669 .RS +4
670 .TP
671 .ie t \(bu
672 .el o
673 If \fB%U\fR or \fB%W\fR is specified, and if weekday and/or year are not given,
674 and month and day of month are not given, \fBstrptime()\fR will assume the
675 weekday value and/or the year value as the value of the \fBtm_wday\fR field
676 and/or \fBtm_year\fR field of the input \fBtm struct\fR. Then,
677 \fBstrptime()\fR will calculate the month and day-of-month and assign
678 \fBtm_month\fR, \fBtm_mday\fR, and/or \fBtm_year\fR.
679 .RE
680 .RS +4
681 .TP
682 .ie t \(bu
683 .el o
684 If \fB%p\fR is specified and if hour is not specified, \fBstrptime()\fR will
685 reference, and if needed, update the \fBtm_hour\fR member. If the \fBam_pm\fR
686 input is p.m. and the input \fBtm_hour\fR value is between 0 - 11,
687 \fBstrptime()\fR will add 12 hours and update \fBtm_hour\fR. If the
688 \fBam_pm\fR input is a.m. and input \fBtm_hour\fR value is between 12 - 23,
689 \fBstrptime()\fR will subtract 12 hours and update \fBtm_hour\fR.
690 .RE
691 .SH RETURN VALUES
692 .LP
693 Upon successful completion, \fBstrptime()\fR returns a pointer to the character
694 following the last character parsed. Otherwise, a null pointer is returned.
695 .SH USAGE
696 .LP
697 Several "same as" formats, and the special processing of white-space characters
698 are provided in order to ease the use of identical \fIformat\fR strings for
699 \fBstrftime\fR(3C) and \fBstrptime()\fR.
700 .LP
701 The \fBstrptime()\fR function tries to calculate \fBtm_year\fR, \fBtm_mon\fR,
702 and \fBtm_mday\fR when given incomplete input. This allows the \fBstruct tm\fR
703 created by \fBstrptime()\fR to be passed to \fBmktime\fR(3C) to produce a
704 \fBtime_t\fR value for dates and times that are representable by a
705 \fBtime_t\fR. As an example, since \fBmktime()\fR ignores \fBtm_yday\fR,
706 \fBstrptime()\fR calculates \fBtm_mon\fR and \fBtm_mday\fR as well as filling
707 in \fBtm_yday\fR when \fB%j\fR is specified without otherwise specifying a
708 month and day within month.
709 .SH ATTRIBUTES
710 .LP
711 See \fBattributes\fR(5) for descriptions of the following attributes:
712 .TS
713 box;
714 c | c
715 l | l .
716 ATTRIBUTE TYPE ATTRIBUTE VALUE
717 _
718 CSI Enabled
719 _
720 Interface Stability See below.
721 _
722 MT-Level MT-Safe
723 _
724 Standard See \fBstandards\fR(5) for \fBstrptime()\fR.
725 .TE
727 .LP
728 The \fBstrptime()\fR function is Standard. The \fBstrptime_l()\fR function
729 is Uncommitted.
730 .SH SEE ALSO
731 .LP
732 \fBctime\fR(3C), \fBgetdate\fR(3C), \fBisspace\fR(3C), \fBmktime\fR(3C),
733 \fBnewlocale\fR(3C),
734 \fBsetlocale\fR(3C), \fBstrftime\fR(3C), \fBuselocale\fR(3C),
735 \fBattributes\fR(5), \fBenviron\fR(5),
736 \fBstandards\fR(5)