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