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