]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk> |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08 | |
26 | .\" Modified, aeb, 2000-04-07 | |
27 | .\" Updated from glibc docs, C. Scott Ananian, 2001-08-25 | |
28 | .\" Modified, aeb, 2001-08-31 | |
29 | .\" Modified, wharms 2001-11-12, remark on white space and example | |
30 | .\" | |
4b8c67d9 | 31 | .TH STRPTIME 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
32 | .SH NAME |
33 | strptime \- convert a string representation of time to a time tm structure | |
34 | .SH SYNOPSIS | |
b80f966b | 35 | .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" |
fea681da MK |
36 | .br |
37 | .B #include <time.h> | |
68e4db0a | 38 | .PP |
fea681da MK |
39 | .BI "char *strptime(const char *" s ", const char *" format , |
40 | .BI "struct tm *" tm ); | |
41 | .SH DESCRIPTION | |
42 | The | |
63aa9df0 | 43 | .BR strptime () |
77f48c37 MK |
44 | function is the converse of |
45 | .BR strftime (3); | |
46 | it converts the character string pointed to by | |
fea681da MK |
47 | .I s |
48 | to values which are stored in the | |
77f48c37 | 49 | "broken-down time" |
fea681da MK |
50 | structure pointed to by |
51 | .IR tm , | |
52 | using the format specified by | |
53 | .IR format . | |
847e0d88 | 54 | .PP |
77f48c37 MK |
55 | The broken-down time structure |
56 | .I tm | |
57 | is defined in | |
58 | .IR <time.h> | |
59 | as follows: | |
51f5698d | 60 | .PP |
77f48c37 | 61 | .in +4n |
bdd915e2 | 62 | .EX |
77f48c37 | 63 | struct tm { |
d2fdb1e3 MK |
64 | int tm_sec; /* Seconds (0\-60) */ |
65 | int tm_min; /* Minutes (0\-59) */ | |
66 | int tm_hour; /* Hours (0\-23) */ | |
67 | int tm_mday; /* Day of the month (1\-31) */ | |
68 | int tm_mon; /* Month (0\-11) */ | |
69 | int tm_year; /* Year \- 1900 */ | |
70 | int tm_wday; /* Day of the week (0\-6, Sunday = 0) */ | |
71 | int tm_yday; /* Day in the year (0\-365, 1 Jan = 0) */ | |
77f48c37 MK |
72 | int tm_isdst; /* Daylight saving time */ |
73 | }; | |
bdd915e2 | 74 | .EE |
77f48c37 | 75 | .in |
847e0d88 | 76 | .PP |
77f48c37 MK |
77 | For more details on the |
78 | .I tm | |
79 | structure, see | |
80 | .BR ctime (3). | |
847e0d88 | 81 | .PP |
77f48c37 | 82 | The |
fea681da | 83 | .I format |
77f48c37 | 84 | argument |
fea681da MK |
85 | is a character string that consists of field descriptors and text characters, |
86 | reminiscent of | |
87 | .BR scanf (3). | |
88 | Each field descriptor consists of a | |
89 | .B % | |
90 | character followed by another character that specifies the replacement | |
91 | for the field descriptor. | |
c13182ef MK |
92 | All other characters in the |
93 | .I format | |
fea681da MK |
94 | string must have a matching character in the input string, |
95 | except for whitespace, which matches zero or more | |
96 | whitespace characters in the input string. | |
97 | There should be white\%space or other alphanumeric characters | |
98 | between any two field descriptors. | |
99 | .PP | |
60a90ecd MK |
100 | The |
101 | .BR strptime () | |
102 | function processes the input string from left | |
c13182ef MK |
103 | to right. |
104 | Each of the three possible input elements (whitespace, | |
105 | literal, or format) are handled one after the other. | |
0e704469 | 106 | If the input cannot be matched to the format string, the function stops. |
c13182ef | 107 | The remainder of the format and input strings are not processed. |
fea681da MK |
108 | .PP |
109 | The supported input field descriptors are listed below. | |
b458e1bf | 110 | In case a text string (such as the name of a day of the week or a month name) |
fea681da MK |
111 | is to be matched, the comparison is case insensitive. |
112 | In case a number is to be matched, leading zeros are | |
113 | permitted but not required. | |
114 | .TP | |
115 | .B %% | |
116 | The | |
117 | .B % | |
118 | character. | |
119 | .TP | |
120 | .BR %a " or " %A | |
b458e1bf | 121 | The name of the day of the week according to the current locale, |
fea681da MK |
122 | in abbreviated form or the full name. |
123 | .TP | |
124 | .BR %b " or " %B " or " %h | |
125 | The month name according to the current locale, | |
126 | in abbreviated form or the full name. | |
127 | .TP | |
128 | .B %c | |
129 | The date and time representation for the current locale. | |
130 | .TP | |
131 | .B %C | |
d2fdb1e3 | 132 | The century number (0\(en99). |
fea681da MK |
133 | .TP |
134 | .BR %d " or " %e | |
d2fdb1e3 | 135 | The day of month (1\(en31). |
fea681da MK |
136 | .TP |
137 | .B %D | |
5adafd6d MK |
138 | Equivalent to |
139 | .BR %m/%d/%y . | |
c13182ef | 140 | (This is the American style date, very confusing |
5adafd6d MK |
141 | to non-Americans, especially since |
142 | .B %d/%m/%y | |
143 | is widely used in Europe. | |
144 | The ISO 8601 standard format is | |
145 | .BR %Y-%m-%d .) | |
fea681da | 146 | .TP |
0daa9e92 | 147 | .B %H |
d2fdb1e3 | 148 | The hour (0\(en23). |
fea681da | 149 | .TP |
0daa9e92 | 150 | .B %I |
d2fdb1e3 | 151 | The hour on a 12-hour clock (1\(en12). |
fea681da MK |
152 | .TP |
153 | .B %j | |
d2fdb1e3 | 154 | The day number in the year (1\(en366). |
fea681da MK |
155 | .TP |
156 | .B %m | |
d2fdb1e3 | 157 | The month number (1\(en12). |
fea681da MK |
158 | .TP |
159 | .B %M | |
d2fdb1e3 | 160 | The minute (0\(en59). |
fea681da MK |
161 | .TP |
162 | .B %n | |
163 | Arbitrary whitespace. | |
164 | .TP | |
165 | .B %p | |
6387216b MK |
166 | The locale's equivalent of AM or PM. |
167 | (Note: there may be none.) | |
fea681da MK |
168 | .TP |
169 | .B %r | |
170 | The 12-hour clock time (using the locale's AM or PM). | |
5adafd6d MK |
171 | In the POSIX locale equivalent to |
172 | .BR "%I:%M:%S %p" . | |
c6fa0841 MK |
173 | If |
174 | .I t_fmt_ampm | |
175 | is empty in the | |
097585ed | 176 | .B LC_TIME |
0e704469 | 177 | part of the current locale, |
d9bfdb9c | 178 | then the behavior is undefined. |
fea681da MK |
179 | .TP |
180 | .B %R | |
5adafd6d MK |
181 | Equivalent to |
182 | .BR %H:%M . | |
fea681da MK |
183 | .TP |
184 | .B %S | |
d2fdb1e3 | 185 | The second (0\(en60; 60 may occur for leap seconds; |
c13182ef | 186 | earlier also 61 was allowed). |
fea681da MK |
187 | .TP |
188 | .B %t | |
189 | Arbitrary whitespace. | |
190 | .TP | |
191 | .B %T | |
5adafd6d MK |
192 | Equivalent to |
193 | .BR %H:%M:%S . | |
fea681da MK |
194 | .TP |
195 | .B %U | |
d2fdb1e3 | 196 | The week number with Sunday the first day of the week (0\(en53). |
fea681da MK |
197 | The first Sunday of January is the first day of week 1. |
198 | .TP | |
199 | .B %w | |
d2fdb1e3 | 200 | The ordinal number of the day of the week (0\(en6), with Sunday = 0. |
fea681da MK |
201 | .TP |
202 | .B %W | |
d2fdb1e3 | 203 | The week number with Monday the first day of the week (0\(en53). |
fea681da MK |
204 | The first Monday of January is the first day of week 1. |
205 | .TP | |
206 | .B %x | |
207 | The date, using the locale's date format. | |
208 | .TP | |
209 | .B %X | |
210 | The time, using the locale's time format. | |
211 | .TP | |
212 | .B %y | |
d2fdb1e3 MK |
213 | The year within century (0\(en99). |
214 | When a century is not otherwise specified, values in the range 69\(en99 refer | |
215 | to years in the twentieth century (1969\(en1999); values in the | |
216 | range 00\(en68 refer to years in the twenty-first century (2000\(en2068). | |
fea681da MK |
217 | .TP |
218 | .B %Y | |
219 | The year, including century (for example, 1991). | |
dd3568a1 | 220 | .PP |
fea681da | 221 | Some field descriptors can be modified by the E or O modifier characters |
c13182ef MK |
222 | to indicate that an alternative format or specification should be used. |
223 | If the | |
fea681da MK |
224 | alternative format or specification does not exist in the current locale, the |
225 | unmodified field descriptor is used. | |
dd3568a1 | 226 | .PP |
fea681da MK |
227 | The E modifier specifies that the input string may contain |
228 | alternative locale-dependent versions of the date and time representation: | |
229 | .TP | |
230 | .B %Ec | |
231 | The locale's alternative date and time representation. | |
232 | .TP | |
233 | .B %EC | |
234 | The name of the base year (period) in the locale's alternative representation. | |
235 | .TP | |
236 | .B %Ex | |
237 | The locale's alternative date representation. | |
238 | .TP | |
239 | .B %EX | |
240 | The locale's alternative time representation. | |
241 | .TP | |
242 | .B %Ey | |
5adafd6d MK |
243 | The offset from |
244 | .B %EC | |
245 | (year only) in the locale's alternative representation. | |
fea681da MK |
246 | .TP |
247 | .B %EY | |
248 | The full alternative year representation. | |
dd3568a1 | 249 | .PP |
fea681da MK |
250 | The O modifier specifies that the numerical input may be in an |
251 | alternative locale-dependent format: | |
252 | .TP | |
253 | .BR %Od " or " %Oe | |
254 | The day of the month using the locale's alternative numeric symbols; | |
255 | leading zeros are permitted but not required. | |
256 | .TP | |
257 | .B %OH | |
258 | The hour (24-hour clock) using the locale's alternative numeric symbols. | |
259 | .TP | |
260 | .B %OI | |
261 | The hour (12-hour clock) using the locale's alternative numeric symbols. | |
262 | .TP | |
263 | .B %Om | |
264 | The month using the locale's alternative numeric symbols. | |
265 | .TP | |
266 | .B %OM | |
267 | The minutes using the locale's alternative numeric symbols. | |
268 | .TP | |
269 | .B %OS | |
270 | The seconds using the locale's alternative numeric symbols. | |
271 | .TP | |
272 | .B %OU | |
273 | The week number of the year (Sunday as the first day of the week) | |
274 | using the locale's alternative numeric symbols. | |
275 | .TP | |
276 | .B %Ow | |
b458e1bf MK |
277 | The ordinal number of the day of the week (Sunday=0), |
278 | using the locale's alternative numeric symbols. | |
fea681da MK |
279 | .TP |
280 | .B %OW | |
281 | The week number of the year (Monday as the first day of the week) | |
282 | using the locale's alternative numeric symbols. | |
283 | .TP | |
284 | .B %Oy | |
5adafd6d MK |
285 | The year (offset from |
286 | .BR %C ) | |
287 | using the locale's alternative numeric symbols. | |
47297adb | 288 | .SH RETURN VALUE |
fea681da | 289 | The return value of the function is a pointer to the first character |
c13182ef MK |
290 | not processed in this function call. |
291 | In case the input string | |
3dd08d1d | 292 | contains more characters than required by the format string, the return |
c13182ef | 293 | value points right after the last consumed input character. |
a40d006b MK |
294 | In case the whole input string is consumed, |
295 | the return value points to the null byte at the end of the string. | |
60a90ecd MK |
296 | If |
297 | .BR strptime () | |
298 | fails to match all | |
0e704469 | 299 | of the format string and therefore an error occurred, the function |
35e21ba7 | 300 | returns NULL. |
2ed47574 PH |
301 | .SH ATTRIBUTES |
302 | For an explanation of the terms used in this section, see | |
303 | .BR attributes (7). | |
304 | .TS | |
305 | allbox; | |
306 | lb lb lb | |
307 | l l l. | |
308 | Interface Attribute Value | |
309 | T{ | |
310 | .BR strptime () | |
311 | T} Thread safety MT-Safe env locale | |
312 | .TE | |
47297adb | 313 | .SH CONFORMING TO |
deb28c12 | 314 | POSIX.1-2001, POSIX.1-2008, SUSv2. |
d597239c | 315 | .SH NOTES |
dd3568a1 | 316 | .PP |
c6fa0841 MK |
317 | In principle, this function does not initialize |
318 | .I tm | |
319 | but | |
33a0ccb2 | 320 | stores only the values specified. |
c6fa0841 MK |
321 | This means that |
322 | .I tm | |
323 | should be initialized before the call. | |
008f1ecc | 324 | Details differ a bit between different UNIX systems. |
5260fe08 | 325 | The glibc implementation does not touch those fields which are not |
d597239c | 326 | explicitly specified, except that it recomputes the |
0daa9e92 | 327 | .I tm_wday |
d597239c | 328 | and |
0daa9e92 | 329 | .I tm_yday |
d597239c | 330 | field if any of the year, month, or day elements changed. |
7fbe05e4 MK |
331 | .\" .PP |
332 | .\" This function is available since libc 4.6.8. | |
333 | .\" Linux libc4 and libc5 includes define the prototype unconditionally; | |
334 | .\" glibc2 includes provide a prototype only when | |
335 | .\" .B _XOPEN_SOURCE | |
336 | .\" or | |
337 | .\" .B _GNU_SOURCE | |
338 | .\" are defined. | |
339 | .\" .PP | |
340 | .\" Before libc 5.4.13 whitespace | |
341 | .\" (and the \(aqn\(aq and \(aqt\(aq specifications) was not handled, | |
342 | .\" no \(aqE\(aq and \(aqO\(aq locale modifier characters were accepted, | |
343 | .\" and the \(aqC\(aq specification was a synonym for the \(aqc\(aq specification. | |
d597239c | 344 | .PP |
f81fb444 | 345 | The \(aqy\(aq (year in century) specification is taken to specify a year |
7fbe05e4 MK |
346 | .\" in the 20th century by libc4 and libc5. |
347 | .\" It is taken to be a year | |
9bc87ed0 | 348 | in the range 1950\(en2049 by glibc 2.0. |
d597239c | 349 | It is taken to be a year in |
9bc87ed0 | 350 | 1969\(en2068 since glibc 2.1. |
d597239c MK |
351 | .\" In libc4 and libc5 the code for %I is broken (fixed in glibc; |
352 | .\" %OI was fixed in glibc 2.2.4). | |
c634028a | 353 | .SS Glibc notes |
fea681da | 354 | For reasons of symmetry, glibc tries to support for |
e511ffb6 | 355 | .BR strptime () |
fea681da | 356 | the same format characters as for |
fb186734 | 357 | .BR strftime (3). |
3dd08d1d | 358 | (In most cases, the corresponding fields are parsed, but no field in |
c6fa0841 | 359 | .I tm |
fea681da MK |
360 | is changed.) |
361 | This leads to | |
362 | .TP | |
363 | .B %F | |
c6fa0841 MK |
364 | Equivalent to |
365 | .BR %Y-%m-%d , | |
366 | the ISO 8601 date format. | |
fea681da MK |
367 | .TP |
368 | .B %g | |
369 | The year corresponding to the ISO week number, but without the century | |
9bc87ed0 | 370 | (0\(en99). |
fea681da MK |
371 | .TP |
372 | .B %G | |
6387216b MK |
373 | The year corresponding to the ISO week number. |
374 | (For example, 1991.) | |
fea681da MK |
375 | .TP |
376 | .B %u | |
9bc87ed0 | 377 | The day of the week as a decimal number (1\(en7, where Monday = 1). |
fea681da MK |
378 | .TP |
379 | .B %V | |
9bc87ed0 | 380 | The ISO 8601:1988 week number as a decimal number (1\(en53). |
fea681da | 381 | If the week (starting on Monday) containing 1 January has four or more days |
c13182ef MK |
382 | in the new year, then it is considered week 1. |
383 | Otherwise, it is the last week | |
fea681da MK |
384 | of the previous year, and the next week is week 1. |
385 | .TP | |
386 | .B %z | |
5b0dc1ba | 387 | An RFC-822/ISO 8601 standard timezone specification. |
fea681da MK |
388 | .TP |
389 | .B %Z | |
390 | The timezone name. | |
dd3568a1 | 391 | .PP |
d9c1ae64 MK |
392 | Similarly, because of GNU extensions to |
393 | .BR strftime (3), | |
5adafd6d MK |
394 | .B %k |
395 | is accepted as a synonym for | |
396 | .BR %H , | |
397 | and | |
398 | .B %l | |
399 | should be accepted | |
400 | as a synonym for | |
401 | .BR %I , | |
402 | and | |
403 | .B %P | |
404 | is accepted as a synonym for | |
405 | .BR %p . | |
fea681da MK |
406 | Finally |
407 | .TP | |
408 | .B %s | |
f49c451a | 409 | The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). |
fea681da | 410 | Leap seconds are not counted unless leap second support is available. |
dd3568a1 | 411 | .PP |
5260fe08 | 412 | The glibc implementation does not require whitespace between |
fea681da | 413 | two field descriptors. |
2b2581ee MK |
414 | .SH EXAMPLE |
415 | The following example demonstrates the use of | |
416 | .BR strptime () | |
417 | and | |
418 | .BR strftime (3). | |
51f5698d | 419 | .PP |
bdd915e2 | 420 | .EX |
53255c2b | 421 | #define _XOPEN_SOURCE |
2b2581ee | 422 | #include <stdio.h> |
af9c7ff2 | 423 | #include <stdlib.h> |
7e6b1afb | 424 | #include <string.h> |
2b2581ee MK |
425 | #include <time.h> |
426 | ||
427 | int | |
428 | main(void) | |
429 | { | |
430 | struct tm tm; | |
431 | char buf[255]; | |
432 | ||
7e6b1afb | 433 | memset(&tm, 0, sizeof(struct tm)); |
29059a65 | 434 | strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm); |
2b2581ee MK |
435 | strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm); |
436 | puts(buf); | |
437 | exit(EXIT_SUCCESS); | |
438 | } | |
bdd915e2 | 439 | .EE |
47297adb | 440 | .SH SEE ALSO |
fea681da MK |
441 | .BR time (2), |
442 | .BR getdate (3), | |
443 | .BR scanf (3), | |
444 | .BR setlocale (3), | |
0a4f8b7b | 445 | .BR strftime (3) |