1STRPTIME(3P)               POSIX Programmer's Manual              STRPTIME(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       strptime — date and time conversion
13

SYNOPSIS

15       #include <time.h>
16
17       char *strptime(const char *restrict buf, const char *restrict format,
18           struct tm *restrict tm);
19

DESCRIPTION

21       The strptime() function shall convert the character string  pointed  to
22       by buf to values which are stored in the tm structure pointed to by tm,
23       using the format specified by format.
24
25       The format is composed of zero or more directives.  Each  directive  is
26       composed  of  one  of the following: one or more white-space characters
27       (as specified by isspace()); an ordinary character (neither '%'  nor  a
28       white-space character); or a conversion specification.
29
30       Each  conversion specification is introduced by the '%' character after
31       which the following appear in sequence:
32
33        *  An optional flag, the zero character ('0') or the <plus-sign> char‐
34           acter ('+'), which is ignored.
35
36        *  An optional field width. If a field width is specified, it shall be
37           interpreted as a string of decimal digits that will  determine  the
38           maximum  number  of  bytes converted for the conversion rather than
39           the number of bytes specified below in the description of the  con‐
40           version specifiers.
41
42        *  An optional E or O modifier.
43
44        *  A  terminating  conversion  specifier  character that indicates the
45           type of conversion to be applied.
46
47       The conversions are determined using the LC_TIME category of  the  cur‐
48       rent  locale. The application shall ensure that there is white-space or
49       other non-alphanumeric characters between any two conversion specifica‐
50       tions  unless  all  of the adjacent conversion specifications convert a
51       known, fixed number of characters. In the following list,  the  maximum
52       number  of  characters  scanned  (excluding  the  one matching the next
53       directive) is as follows:
54
55        *  If a maximum field width is specified, then that number
56
57        *  Otherwise, the pattern "{x}" indicates that the maximum is x
58
59        *  Otherwise, the pattern "[x,y]" indicates that the value shall  fall
60           within the range given (both bounds being inclusive), and the maxi‐
61           mum number of characters scanned shall be the maximum  required  to
62           represent  any value in the range without leading zeros and without
63           a leading <plus-sign>
64
65       The following conversion specifiers are supported.
66
67       The results are unspecified if a modifier is specified with a  flag  or
68       with  a  minimum  field width, or if a field width is specified for any
69       conversion specifier other than C or Y.
70
71       a       The day of the week, using the locale's weekday  names;  either
72               the abbreviated or full name may be specified.
73
74       A       Equivalent to %a.
75
76       b       The  month, using the locale's month names; either the abbrevi‐
77               ated or full name may be specified.
78
79       B       Equivalent to %b.
80
81       c       Replaced by the locale's appropriate date and time  representa‐
82               tion.
83
84       C       All  but  the  last  two  digits of the year {2}; leading zeros
85               shall be permitted but shall not be required. A leading '+'  or
86               '-'  character  shall be permitted before any leading zeros but
87               shall not be required.
88
89       d       The day of the month [01,31]; leading zeros shall be  permitted
90               but shall not be required.
91
92       D       The date as %m/%d/%y.
93
94       e       Equivalent to %d.
95
96       h       Equivalent to %b.
97
98       H       The  hour  (24-hour clock) [00,23]; leading zeros shall be per‐
99               mitted but shall not be required.
100
101       I       The hour (12-hour clock) [01,12]; leading zeros shall  be  per‐
102               mitted but shall not be required.
103
104       j       The  day  number  of the year [001,366]; leading zeros shall be
105               permitted but shall not be required.
106
107       m       The month number [01,12]; leading zeros shall be permitted  but
108               shall not be required.
109
110       M       The  minute [00,59]; leading zeros shall be permitted but shall
111               not be required.
112
113       n       Any white space.
114
115       p       The locale's equivalent of a.m. or p.m.
116
117       r       12-hour clock time using the AM/PM notation  if  t_fmt_ampm  is
118               not  an  empty  string  in  the  LC_TIME portion of the current
119               locale; in the  POSIX  locale,  this  shall  be  equivalent  to
120               %I:%M:%S %p.
121
122       R       The time as %H:%M.
123
124       S       The seconds [00,60]; leading zeros shall be permitted but shall
125               not be required.
126
127       t       Any white space.
128
129       T       The time as %H:%M:%S.
130
131       U       The week number of the year (Sunday as the  first  day  of  the
132               week)  as a decimal number [00,53]; leading zeros shall be per‐
133               mitted but shall not be required.
134
135       w       The weekday as a decimal number [0,6], with 0 representing Sun‐
136               day.
137
138       W       The  week  number  of  the year (Monday as the first day of the
139               week) as a decimal number [00,53]; leading zeros shall be  per‐
140               mitted but shall not be required.
141
142       x       The date, using the locale's date format.
143
144       X       The time, using the locale's time format.
145
146       y       The last two digits of the year. When format contains neither a
147               C conversion specifier nor a Y conversion specifier, values  in
148               the  range  [69,99] shall refer to years 1969 to 1999 inclusive
149               and values in the range [00,68] shall refer to  years  2000  to
150               2068  inclusive; leading zeros shall be permitted but shall not
151               be required. A leading '+' or '-' character shall be  permitted
152               before any leading zeros but shall not be required.
153
154               Note:     It is expected that in a future version of this stan‐
155                         dard the default century inferred from a 2-digit year
156                         will  change.  (This  would  apply  to  all  commands
157                         accepting a 2-digit year as input.)
158
159       Y       The full year {4}; leading zeros shall be permitted  but  shall
160               not  be  required. A leading '+' or '-' character shall be per‐
161               mitted before any leading zeros but shall not be required.
162
163       %       Replaced by %.
164
165   Modified Conversion Specifiers
166       Some conversion specifiers can be modified by  the  E  and  O  modifier
167       characters  to  indicate  that  an  alternative format or specification
168       should be used rather than the one normally used by the unmodified con‐
169       version  specifier. If the alternative format or specification does not
170       exist in the current locale, the behavior shall be as if the unmodified
171       conversion specification were used.
172
173       %Ec     The  locale's alternative appropriate date and time representa‐
174               tion.
175
176       %EC     The name of the base year (period) in the locale's  alternative
177               representation.
178
179       %Ex     The locale's alternative date representation.
180
181       %EX     The locale's alternative time representation.
182
183       %Ey     The  offset  from  %EC  (year only) in the locale's alternative
184               representation.
185
186       %EY     The full alternative year representation.
187
188       %Od     The day of the month using  the  locale's  alternative  numeric
189               symbols;  leading  zeros  shall  be  permitted but shall not be
190               required.
191
192       %Oe     Equivalent to %Od.
193
194       %OH     The hour (24-hour clock) using the locale's alternative numeric
195               symbols.
196
197       %OI     The hour (12-hour clock) using the locale's alternative numeric
198               symbols.
199
200       %Om     The month using the locale's alternative numeric symbols.
201
202       %OM     The minutes using the locale's alternative numeric symbols.
203
204       %OS     The seconds using the locale's alternative numeric symbols.
205
206       %OU     The week number of the year (Sunday as the  first  day  of  the
207               week) using the locale's alternative numeric symbols.
208
209       %Ow     The  number of the weekday (Sunday=0) using the locale's alter‐
210               native numeric symbols.
211
212       %OW     The week number of the year (Monday as the  first  day  of  the
213               week) using the locale's alternative numeric symbols.
214
215       %Oy     The  year  (offset  from  %C)  using  the  locale's alternative
216               numeric symbols.
217
218       A conversion specification composed of white-space characters  is  exe‐
219       cuted  by  scanning  input up to the first character that is not white-
220       space (which remains unscanned), or until no  more  characters  can  be
221       scanned.
222
223       A conversion specification that is an ordinary character is executed by
224       scanning the next character from the buffer. If the  character  scanned
225       from  the  buffer  differs  from  the one comprising the directive, the
226       directive fails, and the differing  and  subsequent  characters  remain
227       unscanned.
228
229       A  series  of conversion specifications composed of %n, %t, white-space
230       characters, or any combination is executed by scanning up to the  first
231       character  that  is not white space (which remains unscanned), or until
232       no more characters can be scanned.
233
234       Any other conversion specification is executed by  scanning  characters
235       until  a  character matching the next directive is scanned, or until no
236       more characters can be scanned. These characters, except the one match‐
237       ing  the next directive, are then compared to the locale values associ‐
238       ated with the conversion specifier. If a match is found, values for the
239       appropriate tm structure members are set to values corresponding to the
240       locale information. Case is ignored when matching items in buf such  as
241       month  or  weekday names. If no match is found, strptime() fails and no
242       more characters are scanned.
243

RETURN VALUE

245       Upon successful completion, strptime() shall return a  pointer  to  the
246       character  following  the  last  character  parsed.  Otherwise,  a null
247       pointer shall be returned.
248

ERRORS

250       No errors are defined.
251
252       The following sections are informative.
253

EXAMPLES

255   Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds
256       The following example demonstrates the use of strptime() to  convert  a
257       string  into  broken-down  time. The broken-down time is then converted
258       into seconds since the Epoch using mktime().
259
260
261           #include <time.h>
262           ...
263
264           struct tm tm;
265           time_t t;
266
267           if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
268               /* Handle error */;
269
270           printf("year: %d; month: %d; day: %d;\n",
271                   tm.tm_year, tm.tm_mon, tm.tm_mday);
272           printf("hour: %d; minute: %d; second: %d\n",
273                   tm.tm_hour, tm.tm_min, tm.tm_sec);
274           printf("week day: %d; year day: %d\n", tm.tm_wday, tm.tm_yday);
275
276           tm.tm_isdst = -1;      /* Not set by strptime(); tells mktime()
277                                     to determine whether daylight saving time
278                                     is in effect */
279           t = mktime(&tm);
280           if (t == -1)
281               /* Handle error */;
282           printf("seconds since the Epoch: %ld\n", (long) t);"
283

APPLICATION USAGE

285       Several ``equivalent to'' formats and the special processing of  white-
286       space  characters  are  provided  in order to ease the use of identical
287       format strings for strftime() and strptime().
288
289       It should be noted that dates constructed by  the  strftime()  function
290       with  the  %Y or %C%y conversion specifiers may have values larger than
291       9999. If the strptime() function is used to read such values using %C%y
292       or  %Y,  the year values will be truncated to four digits. Applications
293       should use %+w%y or %+xY with w and x set large enough to  contain  the
294       full value of any years that will be printed or scanned.
295
296       See also the APPLICATION USAGE section in strftime().
297
298       It  is  unspecified whether multiple calls to strptime() using the same
299       tm structure will update the current contents of the structure or over‐
300       write  all  contents  of  the structure. Conforming applications should
301       make a single call to strptime() with a format and all data  needed  to
302       completely specify the date and time being converted.
303

RATIONALE

305       See the RATIONALE section for strftime().
306

FUTURE DIRECTIONS

308       None.
309

SEE ALSO

311       fprintf(), fscanf(), strftime(), time()
312
313       The Base Definitions volume of POSIX.1‐2017, <time.h>
314
316       Portions  of  this text are reprinted and reproduced in electronic form
317       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
318       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
319       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
320       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
321       event of any discrepancy between this version and the original IEEE and
322       The  Open Group Standard, the original IEEE and The Open Group Standard
323       is the referee document. The original Standard can be  obtained  online
324       at http://www.opengroup.org/unix/online.html .
325
326       Any  typographical  or  formatting  errors that appear in this page are
327       most likely to have been introduced during the conversion of the source
328       files  to  man page format. To report such errors, see https://www.ker
329       nel.org/doc/man-pages/reporting_bugs.html .
330
331
332
333IEEE/The Open Group                  2017                         STRPTIME(3P)
Impressum