The first function is a rather low-level interface. It is nevertheless
frequently used in user programs since it is better known. Its
implementation and the interface though is heavily influenced by the
getdate
function which is defined and implemented in terms of
calls to strptime
.
strptime
function parses the input string s according
to the format string fmt and stores the found values in the
structure tp.
The input string can be retrieved in any way. It does not matter
whether it was generated by a strftime
call or made up directly
by a program. It is also not necessary that the content is in any
human-recognizable format. I.e., it is OK if a date is written like
"02:1999:9"
which is not understandable without context. As long
the format string fmt matches the format of the input string
everything goes.
The format string consists of the same components as the format string
for the strftime
function. The only difference is that the flags
_
, -
, 0
, and ^
are not allowed.
Several of the formats which strftime
handled differently do the
same work in strptime
since differences like case of the output
do not matter. For symmetry reasons all formats are supported, though.
The modifiers E
and O
are also allowed everywhere the
strftime
function allows them.
The formats are:
%a
%A
%b
%B
%h
%c
%Ec
%c
but the locale's alternative date and time format is used.
%C
%y
format.
%EC
%C
it makes sometimes sense to use this format since in
some cultures it is required to specify years relative to periods
instead of using the Gregorian years.
%d
%e
1
through 31
).
Leading zeroes are permitted but not required.
%Od
%Oe
%d
but the locale's alternative numeric symbols are used.
Leading zeroes are permitted but not required.
%D
%m/%d/%y
in this place.
%F
%Y-%m-%d
which is the ISO 8601 date
format.
This is a GNU extension following an ISO C 9X extension to
strftime
.
%g
00
through 99
).
Note: This is not really implemented currently. The format is
recognized, input is consumed but no field in tm is set.
This format is a GNU extension following a GNU extension of strftime
.
%G
strftime
.
%H
%k
00
through
23
).
%k
is a GNU extension following a GNU extension of strftime
.
%OH
%H
but using the locale's alternative numeric symbols are used.
%I
%l
01
through
12
).
%l
is a GNU extension following a GNU extension of strftime
.
%OI
%I
but using the locale's alternative numeric symbols are used.
%j
1
through 366
).
Leading zeroes are permitted but not required.
%m
1
through 12
).
Leading zeroes are permitted but not required.
%Om
%m
but using the locale's alternative numeric symbols are used.
%M
0
through 59
).
Leading zeroes are permitted but not required.
%OM
%M
but using the locale's alternative numeric symbols are used.
%n
%t
%p
%P
%I
or %l
is also used.
Another complication is that the locale might not define these values at
all and therefore the conversion fails.
%P
is a GNU extension following a GNU extension to strftime
.
%r
%R
%H:%M
.
%R
is a GNU extension following a GNU extension to strftime
.
%s
%s
is a GNU extension following a GNU extension to strftime
.
%S
0
through 61
).
Leading zeroes are permitted but not required.
Please note the nonsense with 61
being allowed. This is what the
Unix specification says. They followed the stupid decision once made to
allow double leap seconds. These do not exist but the myth persists.
%OS
%S
but using the locale's alternative numeric symbols are used.
%T
%H:%M:%S
in this place.
%u
1
through
7
), Monday being 1
.
Leading zeroes are permitted but not required.
Note: This is not really implemented currently. The format is
recognized, input is consumed but no field in tm is set.
%U
0
through 53
).
Leading zeroes are permitted but not required.
%OU
%U
but using the locale's alternative numeric symbols are used.
%V
1
through 53
).
Leading zeroes are permitted but not required.
Note: This is not really implemented currently. The format is
recognized, input is consumed but no field in tm is set.
%w
0
through
6
), Sunday being 0
.
Leading zeroes are permitted but not required.
Note: This is not really implemented currently. The format is
recognized, input is consumed but no field in tm is set.
%Ow
%w
but using the locale's alternative numeric symbols are used.
%W
0
through 53
).
Leading zeroes are permitted but not required.
Note: This is not really implemented currently. The format is
recognized, input is consumed but no field in tm is set.
%OW
%W
but using the locale's alternative numeric symbols are used.
%x
%Ex
%x
but the locale's alternative data representation is used.
%X
%EX
%X
but the locale's alternative time representation is used.
%y
0
through
99
).
Leading zeroes are permitted but not required.
Please note that it is at least questionable to use this format without
the %C
format. The strptime
function does regard input
values in the range @math{68} to @math{99} as the years @math{1969} to
@math{1999} and the values @math{0} to @math{68} as the years
@math{2000} to @math{2068}. But maybe this heuristic fails for some
input data.
Therefore it is best to avoid %y
completely and use %Y
instead.
%Ey
%EC
in the locale's alternative representation.
%Oy
%C
) using the locale's alternative
numeric symbols.
%Y
%EY
%z
%a, %d %b %Y %H:%M:%S %z
in this place.
This is the full ISO 8601 date and time format.
%Z
%%
All other characters in the format string must have a matching character in the input string. Exceptions are white spaces in the input string which can match zero or more white space characters in the input string.
The strptime
function processes the input string from right to
left. Each of the three possible input elements (white space, literal,
or format) are handled one after the other. If the input cannot be
matched to the format string the function stops. The remainder of the
format and input strings are not processed.
The return value of the function is a pointer to the first character not
processed in this function call. In case the input string contains more
characters than required by the format string the return value points
right after the last consumed input character. In case the whole input
string is consumed the return value points to the NUL byte at the end of
the string. If strptime
fails to match all of the format string
and therefore an error occurred the function returns NULL
.
The specification of the function in the XPG standard is rather vague. It leaves out a few important pieces of information. Most important it does not specify what happens to those elements of tm which are not directly initialized by the different formats. Various implementations on different Unix systems vary here.
The GNU libc implementation does not touch those fields which are not
directly initialized. Exceptions are the tm_wday
and
tm_yday
elements which are recomputed if any of the year, month,
or date elements changed. This has two implications:
strptime
function for a new input string one
has to prepare the structure passed in as the tm. Normally this
will mean that all values are initialized to zero. Alternatively one
can use all fields to values like INT_MAX
which allows to
determine which elements were set by the function call. Zero does not
work here since it is a valid value for many of the fields.
Careful initialization is necessary if one wants to find out whether a
certain field in tm was initialized by the function call.
struct tm
value in several strptime
calls in a row. A useful application of this is for example the parsing
of two separate strings, one containing the date information, the other
the time information. By parsing both one after the other without
clearing the structure in between one can construct a complete
broken-down time.
The following example shows a function which parses a string which is supposed to contain the date information in either US style or ISO 8601 form.
const char * parse_date (const char *input, struct tm *tm) { const char *cp; /* First clear the result structure. */ memset (tm, '\0', sizeof (*tm)); /* Try the ISO format first. */ cp = strptime (input, "%F", tm); if (cp == NULL) { /* Does not match. Try the US form. */ cp = strptime (input, "%D", tm); } return cp; }
Go to the first, previous, next, last section, table of contents.