1STRPTIME(3P) POSIX Programmer's Manual STRPTIME(3P)
2
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
13 strptime — date and time conversion
14
16 #include <time.h>
17 char *strptime(const char *restrict buf, const char *restrict format,
19 struct tm *restrict tm);
20
22 The strptime() function shall convert the character string pointed to
23 by buf to values which are stored in the tm structure pointed to by tm,
24 using the format specified by format.
25 The format is composed of zero or more directives. Each directive is
27 composed of one of the following: one or more white-space characters
28 (as specified by isspace()); an ordinary character (neither '%' nor a
29 white-space character); or a conversion specification.
30 Each conversion specification is introduced by the '%' character after
32 which the following appear in sequence:
33 * An optional flag, the zero character ('0') or the <plus-sign> char‐
35 acter ('+'), which is ignored.
36 * An optional field width. If a field width is specified, it shall be
38 interpreted as a string of decimal digits that will determine the
39 maximum number of bytes converted for the conversion rather than
40 the number of bytes specified below in the description of the con‐
41 version specifiers.
42 * An optional E or O modifier.
44 * A terminating conversion specifier character that indicates the
46 type of conversion to be applied.
47 The conversions are determined using the LC_TIME category of the cur‐
49 rent locale. The application shall ensure that there is white-space or
50 other non-alphanumeric characters between any two conversion specifica‐
51 tions unless all of the adjacent conversion specifications convert a
52 known, fixed number of characters. In the following list, the maximum
53 number of characters scanned (excluding the one matching the next
54 directive) is as follows:
55 * If a maximum field width is specified, then that number
57 * Otherwise, the pattern "{x}" indicates that the maximum is x
59 * Otherwise, the pattern "[x,y]" indicates that the value shall fall
61 within the range given (both bounds being inclusive), and the maxi‐
62 mum number of characters scanned shall be the maximum required to
63 represent any value in the range without leading zeros and without
64 a leading <plus-sign>
65 The following conversion specifiers are supported.
67 The results are unspecified if a modifier is specified with a flag or
69 with a minimum field width, or if a field width is specified for any
70 conversion specifier other than C, F, or Y.
71 a The day of the week, using the locale's weekday names; either
73 the abbreviated or full name may be specified.
74 A Equivalent to %a.
76 b The month, using the locale's month names; either the abbrevi‐
78 ated or full name may be specified.
79 B Equivalent to %b.
81 c Replaced by the locale's appropriate date and time representa‐
83 tion.
84 C All but the last two digits of the year {2}; leading zeros
86 shall be permitted but shall not be required. A leading '+' or
87 '−' character shall be permitted before any leading zeros but
88 shall not be required.
89 d The day of the month [01,31]; leading zeros shall be permitted
91 but shall not be required.
92 D The date as %m/%d/%y.
94 e Equivalent to %d.
96 h Equivalent to %b.
98 H The hour (24-hour clock) [00,23]; leading zeros shall be per‐
100 mitted but shall not be required.
101 I The hour (12-hour clock) [01,12]; leading zeros shall be per‐
103 mitted but shall not be required.
104 j The day number of the year [001,366]; leading zeros shall be
106 permitted but shall not be required.
107 m The month number [01,12]; leading zeros shall be permitted but
109 shall not be required.
110 M The minute [00,59]; leading zeros shall be permitted but shall
112 not be required.
113 n Any white space.
115 p The locale's equivalent of a.m. or p.m.
117 r 12-hour clock time using the AM/PM notation if t_fmt_ampm is
119 not an empty string in the LC_TIME portion of the current
120 locale; in the POSIX locale, this shall be equivalent to
121 %I:%M:%S %p.
122 R The time as %H:%M.
124 S The seconds [00,60]; leading zeros shall be permitted but shall
126 not be required.
127 t Any white space.
129 T The time as %H:%M:%S.
131 U The week number of the year (Sunday as the first day of the
133 week) as a decimal number [00,53]; leading zeros shall be per‐
134 mitted but shall not be required.
135 w The weekday as a decimal number [0,6], with 0 representing Sun‐
137 day.
138 W The week number of the year (Monday as the first day of the
140 week) as a decimal number [00,53]; leading zeros shall be per‐
141 mitted but shall not be required.
142 x The date, using the locale's date format.
144 X The time, using the locale's time format.
146 y The last two digits of the year. When format contains neither a
148 C conversion specifier nor a Y conversion specifier, values in
149 the range [69,99] shall refer to years 1969 to 1999 inclusive
150 and values in the range [00,68] shall refer to years 2000 to
151 2068 inclusive; leading zeros shall be permitted but shall not
152 be required. A leading '+' or '−' character shall be permitted
153 before any leading zeros but shall not be required.
154 Note: It is expected that in a future version of this stan‐
156 dard the default century inferred from a 2-digit year
157 will change. (This would apply to all commands
158 accepting a 2-digit year as input.)
159 Y The full year {4}; leading zeros shall be permitted but shall
161 not be required. A leading '+' or '−' character shall be per‐
162 mitted before any leading zeros but shall not be required.
163 % Replaced by %.
165 Modified Conversion Specifiers
167 Some conversion specifiers can be modified by the E and O modifier
168 characters to indicate that an alternative format or specification
169 should be used rather than the one normally used by the unmodified con‐
170 version specifier. If the alternative format or specification does not
171 exist in the current locale, the behavior shall be as if the unmodified
172 conversion specification were used.
173 %Ec The locale's alternative appropriate date and time representa‐
175 tion.
176 %EC The name of the base year (period) in the locale's alternative
178 representation.
179 %Ex The locale's alternative date representation.
181 %EX The locale's alternative time representation.
183 %Ey The offset from %EC (year only) in the locale's alternative
185 representation.
186 %EY The full alternative year representation.
188 %Od The day of the month using the locale's alternative numeric
190 symbols; leading zeros shall be permitted but shall not be
191 required.
192 %Oe Equivalent to %Od.
194 %OH The hour (24-hour clock) using the locale's alternative numeric
196 symbols.
197 %OI The hour (12-hour clock) using the locale's alternative numeric
199 symbols.
200 %Om The month using the locale's alternative numeric symbols.
202 %OM The minutes using the locale's alternative numeric symbols.
204 %OS The seconds using the locale's alternative numeric symbols.
206 %OU The week number of the year (Sunday as the first day of the
208 week) using the locale's alternative numeric symbols.
209 %Ow The number of the weekday (Sunday=0) using the locale's alter‐
211 native numeric symbols.
212 %OW The week number of the year (Monday as the first day of the
214 week) using the locale's alternative numeric symbols.
215 %Oy The year (offset from %C) using the locale's alternative
217 numeric symbols.
218 A conversion specification composed of white-space characters is exe‐
220 cuted by scanning input up to the first character that is not white-
221 space (which remains unscanned), or until no more characters can be
222 scanned.
223 A conversion specification that is an ordinary character is executed by
225 scanning the next character from the buffer. If the character scanned
226 from the buffer differs from the one comprising the directive, the
227 directive fails, and the differing and subsequent characters remain
228 unscanned.
229 A series of conversion specifications composed of %n, %t, white-space
231 characters, or any combination is executed by scanning up to the first
232 character that is not white space (which remains unscanned), or until
233 no more characters can be scanned.
234 Any other conversion specification is executed by scanning characters
236 until a character matching the next directive is scanned, or until no
237 more characters can be scanned. These characters, except the one match‐
238 ing the next directive, are then compared to the locale values associ‐
239 ated with the conversion specifier. If a match is found, values for the
240 appropriate tm structure members are set to values corresponding to the
241 locale information. Case is ignored when matching items in buf such as
242 month or weekday names. If no match is found, strptime() fails and no
243 more characters are scanned.
244
246 Upon successful completion, strptime() shall return a pointer to the
247 character following the last character parsed. Otherwise, a null
248 pointer shall be returned.
249
251 No errors are defined.
252 The following sections are informative.
254
256 Convert a Data-Plus-Time String to Broken-Down Time and Then into Seconds
257 The following example demonstrates the use of strptime() to convert a
258 string into broken-down time. The broken-down time is then converted
259 into seconds since the Epoch using mktime().
260 #include <time.h>
262 ...
263 struct tm tm;
265 time_t t;
266 if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
268 /* Handle error */;
269 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 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
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 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 See also the APPLICATION USAGE section in strftime().
297 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
305 See the RATIONALE section for strftime().
306
308 None.
309
311 fprintf(), fscanf(), strftime(), time()
312 The Base Definitions volume of POSIX.1‐2008, <time.h>
314
316 Portions of this text are reprinted and reproduced in electronic form
317 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
318 -- Portable Operating System Interface (POSIX), The Open Group Base
319 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
320 cal and Electronics Engineers, Inc and The Open Group. (This is
321 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
322 event of any discrepancy between this version and the original IEEE and
323 The Open Group Standard, the original IEEE and The Open Group Standard
324 is the referee document. The original Standard can be obtained online
325 at http://www.unix.org/online.html .
326 Any typographical or formatting errors that appear in this page are
328 most likely to have been introduced during the conversion of the source
329 files to man page format. To report such errors, see https://www.ker‐
330 nel.org/doc/man-pages/reporting_bugs.html .
331IEEE/The Open Group 2013 STRPTIME(3P)