1STRPTIME(3)                Linux Programmer's Manual               STRPTIME(3)
2
3
4

NAME

6       strptime  - convert a string representation of time to a time tm struc‐
7       ture
8

SYNOPSIS

10       #define _XOPEN_SOURCE /* glibc2 needs this */
11       #include <time.h>
12
13       char *strptime(const char *s, const char *format, struct tm *tm);
14

DESCRIPTION

16       The strptime() function is the converse  function  to  strftime(3)  and
17       converts  the  character  string  pointed  to  by s to values which are
18       stored in the tm structure pointed to by tm, using the format specified
19       by  format.   Here  format is a character string that consists of field
20       descriptors and text characters, reminiscent of scanf(3).   Each  field
21       descriptor consists of a % character followed by another character that
22       specifies the replacement for the field descriptor.  All other  charac‐
23       ters  in  the format string must have a matching character in the input
24       string, except for whitespace, which matches zero  or  more  whitespace
25       characters  in  the  input string.  There should be whitespace or other
26       alphanumeric characters between any two field descriptors.
27
28       The strptime() function processes the input string from left to  right.
29       Each of the three possible input elements (whitespace, literal, or for‐
30       mat) are handled one after the other.  If the input cannot  be  matched
31       to  the  format string the function stops.  The remainder of the format
32       and input strings are not processed.
33
34       The supported input field descriptors are listed below.  In case a text
35       string (such as a weekday or month name) is to be matched, the compari‐
36       son is case insensitive.  In case a number is to  be  matched,  leading
37       zeros are permitted but not required.
38
39       %%     The % character.
40
41       %a or %A
42              The weekday name according to the current locale, in abbreviated
43              form or the full name.
44
45       %b or %B or %h
46              The month name according to the current locale,  in  abbreviated
47              form or the full name.
48
49       %c     The date and time representation for the current locale.
50
51       %C     The century number (0-99).
52
53       %d or %e
54              The day of month (1-31).
55
56       %D     Equivalent  to %m/%d/%y.  (This is the American style date, very
57              confusing to non-Americans, especially since %d/%m/%y is  widely
58              used in Europe.  The ISO 8601 standard format is %Y-%m-%d.)
59
60       %H     The hour (0-23).
61
62       %I     The hour on a 12-hour clock (1-12).
63
64       %j     The day number in the year (1-366).
65
66       %m     The month number (1-12).
67
68       %M     The minute (0-59).
69
70       %n     Arbitrary whitespace.
71
72       %p     The locale's equivalent of AM or PM.  (Note: there may be none.)
73
74       %r     The  12-hour  clock  time (using the locale's AM or PM).  In the
75              POSIX locale equivalent to %I:%M:%S %p.  If t_fmt_ampm is  empty
76              in  the  LC_TIME part of the current locale then the behavior is
77              undefined.
78
79       %R     Equivalent to %H:%M.
80
81       %S     The second (0-60; 60 may occur for leap seconds; earlier also 61
82              was allowed).
83
84       %t     Arbitrary whitespace.
85
86       %T     Equivalent to %H:%M:%S.
87
88       %U     The  week  number  with Sunday the first day of the week (0-53).
89              The first Sunday of January is the first day of week 1.
90
91       %w     The weekday number (0-6) with Sunday = 0.
92
93       %W     The week number with Monday the first day of  the  week  (0-53).
94              The first Monday of January is the first day of week 1.
95
96       %x     The date, using the locale's date format.
97
98       %X     The time, using the locale's time format.
99
100       %y     The year within century (0-99).  When a century is not otherwise
101              specified, values in the range 69-99 refer to years in the twen‐
102              tieth  century  (1969-1999);  values in the range 00-68 refer to
103              years in the twenty-first century (2000-2068).
104
105       %Y     The year, including century (for example, 1991).
106
107       Some field descriptors can be modified by the E or O  modifier  charac‐
108       ters  to indicate that an alternative format or specification should be
109       used.  If the alternative format or specification does not exist in the
110       current locale, the unmodified field descriptor is used.
111
112       The  E modifier specifies that the input string may contain alternative
113       locale-dependent versions of the date and time representation:
114
115       %Ec    The locale's alternative date and time representation.
116
117       %EC    The name of the base year (period) in the  locale's  alternative
118              representation.
119
120       %Ex    The locale's alternative date representation.
121
122       %EX    The locale's alternative time representation.
123
124       %Ey    The offset from %EC (year only) in the locale's alternative rep‐
125              resentation.
126
127       %EY    The full alternative year representation.
128
129       The O modifier specifies that the numerical input may be in an alterna‐
130       tive locale-dependent format:
131
132       %Od or %Oe
133              The day of the month using the locale's alternative numeric sym‐
134              bols; leading zeros are permitted but not required.
135
136       %OH    The hour (24-hour clock) using the locale's alternative  numeric
137              symbols.
138
139       %OI    The  hour (12-hour clock) using the locale's alternative numeric
140              symbols.
141
142       %Om    The month using the locale's alternative numeric symbols.
143
144       %OM    The minutes using the locale's alternative numeric symbols.
145
146       %OS    The seconds using the locale's alternative numeric symbols.
147
148       %OU    The week number of the year (Sunday as  the  first  day  of  the
149              week) using the locale's alternative numeric symbols.
150
151       %Ow    The number of the weekday (Sunday=0) using the locale's alterna‐
152              tive numeric symbols.
153
154       %OW    The week number of the year (Monday as  the  first  day  of  the
155              week) using the locale's alternative numeric symbols.
156
157       %Oy    The year (offset from %C) using the locale's alternative numeric
158              symbols.
159
160       The broken-down time structure tm is defined in <time.h> as follows:
161
162           struct tm {
163               int tm_sec;        /* seconds */
164               int tm_min;        /* minutes */
165               int tm_hour;       /* hours */
166               int tm_mday;       /* day of the month */
167               int tm_mon;        /* month */
168               int tm_year;       /* year */
169               int tm_wday;       /* day of the week */
170               int tm_yday;       /* day in the year */
171               int tm_isdst;      /* daylight saving time */
172           };
173

RETURN VALUE

175       The return value of the function is a pointer to  the  first  character
176       not processed in this function call.  In case the input string contains
177       more characters than required by the format  string  the  return  value
178       points  right  after  the  last  consumed input character.  In case the
179       whole input string is consumed the return value points to the null byte
180       at the end of the string.  If strptime() fails to match all of the for‐
181       mat string and therefore an error occurred the function returns NULL.
182

CONFORMING TO

184       SUSv2, POSIX.1-2001.
185

NOTES

187       In principle, this function does not initialize tm but only stores  the
188       values  specified.  This means that tm should be initialized before the
189       call.  Details differ a bit between different Unix systems.  The  glibc
190       implementation  does  not  touch  those fields which are not explicitly
191       specified, except that it recomputes the tm_wday and tm_yday  field  if
192       any of the year, month, or day elements changed.
193
194       This  function  is  available  since libc 4.6.8.  Linux libc4 and libc5
195       includes define the prototype unconditionally; glibc2 includes  provide
196       a prototype only when _XOPEN_SOURCE or _GNU_SOURCE are defined.
197
198       Before  libc 5.4.13 whitespace (and the 'n' and 't' specifications) was
199       not handled, no 'E' and 'O' locale modifier characters  were  accepted,
200       and the 'C' specification was a synonym for the 'c' specification.
201
202       The  'y'  (year in century) specification is taken to specify a year in
203       the 20th century by libc4 and libc5.  It is taken to be a year  in  the
204       range  1950-2049  by  glibc 2.0.  It is taken to be a year in 1969-2068
205       since glibc 2.1.
206
207   Glibc Notes
208       For reasons of symmetry, glibc tries to support for strptime() the same
209       format characters as for strftime(3).  (In most cases the corresponding
210       fields are parsed, but no field in tm is changed.)  This leads to
211
212       %F     Equivalent to %Y-%m-%d, the ISO 8601 date format.
213
214       %g     The year corresponding to the ISO week number, but  without  the
215              century (0-99).
216
217       %G     The  year  corresponding  to the ISO week number.  (For example,
218              1991.)
219
220       %u     The day of the week as a decimal number (1-7, where Monday = 1).
221
222       %V     The ISO 8601:1988 week number as a decimal  number  (1-53).   If
223              the  week  (starting on Monday) containing 1 January has four or
224              more days in the new year, then it is considered week 1.  Other‐
225              wise,  it  is  the  last week of the previous year, and the next
226              week is week 1.
227
228       %z     An RFC-822/ISO 8601 standard timezone specification.
229
230       %Z     The timezone name.
231
232       Similarly, because of GNU extensions to strftime(3), %k is accepted  as
233       a synonym for %H, and %l should be accepted as a synonym for %I, and %P
234       is accepted as a synonym for %p.  Finally
235
236       %s     The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000
237              (UTC).   Leap seconds are not counted unless leap second support
238              is available.
239
240       The glibc implementation does not require whitespace between two  field
241       descriptors.
242

EXAMPLE

244       The  following  example  demonstrates  the  use of strptime() and strf‐
245       time(3).
246
247       #define _XOPEN_SOURCE
248       #include <stdio.h>
249       #include <stdlib.h>
250       #include <string.h>
251       #include <time.h>
252
253       int
254       main(void)
255       {
256           struct tm tm;
257           char buf[255];
258
259           memset(&tm, 0, sizeof(struct tm));
260           strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
261           strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
262           puts(buf);
263           exit(EXIT_SUCCESS);
264       }
265

SEE ALSO

267       time(2),  getdate(3),   scanf(3),   setlocale(3),   strftime(3),   fea‐
268       ture_test_macros(7)
269

COLOPHON

271       This  page  is  part of release 3.25 of the Linux man-pages project.  A
272       description of the project, and information about reporting  bugs,  can
273       be found at http://www.kernel.org/doc/man-pages/.
274
275
276
277GNU                               2009-12-05                       STRPTIME(3)
Impressum