Debian Codegraph @

upstream/debian-unstable/man3/strptime.3

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