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