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
12 strptime — date and time conversion
13
15 #include <time.h>
16 char *strptime(const char *restrict buf, const char *restrict format,
18 struct tm *restrict tm);
19
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 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 Each conversion specification is introduced by the '%' character after
31 which the following appear in sequence:
32 * An optional flag, the zero character ('0') or the <plus-sign> char‐
34 acter ('+'), which is ignored.
35 * 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 * An optional E or O modifier.
43 * A terminating conversion specifier character that indicates the
45 type of conversion to be applied.
46 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 * If a maximum field width is specified, then that number
56 * Otherwise, the pattern "{x}" indicates that the maximum is x
58 * 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 The following conversion specifiers are supported.
66 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 a The day of the week, using the locale's weekday names; either
72 the abbreviated or full name may be specified.
73 A Equivalent to %a.
75 b The month, using the locale's month names; either the abbrevi‐
77 ated or full name may be specified.
78 B Equivalent to %b.
80 c Replaced by the locale's appropriate date and time representa‐
82 tion.
83 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 d The day of the month [01,31]; leading zeros shall be permitted
90 but shall not be required.
91 D The date as %m/%d/%y.
93 e Equivalent to %d.
95 h Equivalent to %b.
97 H The hour (24-hour clock) [00,23]; leading zeros shall be per‐
99 mitted but shall not be required.
100 I The hour (12-hour clock) [01,12]; leading zeros shall be per‐
102 mitted but shall not be required.
103 j The day number of the year [001,366]; leading zeros shall be
105 permitted but shall not be required.
106 m The month number [01,12]; leading zeros shall be permitted but
108 shall not be required.
109 M The minute [00,59]; leading zeros shall be permitted but shall
111 not be required.
112 n Any white space.
114 p The locale's equivalent of a.m. or p.m.
116 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 R The time as %H:%M.
123 S The seconds [00,60]; leading zeros shall be permitted but shall
125 not be required.
126 t Any white space.
128 T The time as %H:%M:%S.
130 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 w The weekday as a decimal number [0,6], with 0 representing Sun‐
136 day.
137 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 x The date, using the locale's date format.
143 X The time, using the locale's time format.
145 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 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 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 % Replaced by %.
164 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 %Ec The locale's alternative appropriate date and time representa‐
174 tion.
175 %EC The name of the base year (period) in the locale's alternative
177 representation.
178 %Ex The locale's alternative date representation.
180 %EX The locale's alternative time representation.
182 %Ey The offset from %EC (year only) in the locale's alternative
184 representation.
185 %EY The full alternative year representation.
187 %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 %Oe Equivalent to %Od.
193 %OH The hour (24-hour clock) using the locale's alternative numeric
195 symbols.
196 %OI The hour (12-hour clock) using the locale's alternative numeric
198 symbols.
199 %Om The month using the locale's alternative numeric symbols.
201 %OM The minutes using the locale's alternative numeric symbols.
203 %OS The seconds using the locale's alternative numeric symbols.
205 %OU The week number of the year (Sunday as the first day of the
207 week) using the locale's alternative numeric symbols.
208 %Ow The number of the weekday (Sunday=0) using the locale's alter‐
210 native numeric symbols.
211 %OW The week number of the year (Monday as the first day of the
213 week) using the locale's alternative numeric symbols.
214 %Oy The year (offset from %C) using the locale's alternative
216 numeric symbols.
217 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 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 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 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
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
250 No errors are defined.
251 The following sections are informative.
253
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 #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‐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 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 .
330IEEE/The Open Group 2017 STRPTIME(3P)