he first function is rather low-level. It is nevertheless frequently
used in software since it is better known. Its interface and
implementation are 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 its results in the
structure tp.
The input string could be generated by a strftime
call or
obtained any other way. It does not need to be in a human-recognizable
format; e.g. a date passed as "02:1999:9"
is acceptable, even
though it is ambiguous without context. As long as the format string
fmt matches the input string the function will succeed.
The format string consists of the same components as the format string
of the strftime
function. The only difference is that the flags
_
, -
, 0
, and ^
are not allowed.
Several of the distinct formats of strftime
do the same work in
strptime
since differences like case of the input do not matter.
For reasons of symmetry 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 sometimes makes sense to use this format since some
cultures represent years relative to the beginning of eras instead of
using the Gregorian years.
%d
%e
1
through 31
).
Leading zeroes are permitted but not required.
%Od
%Oe
%d
but using the locale's alternative numeric symbols.
Leading zeroes are permitted but not required.
%D
%m/%d/%y
.
%F
%Y-%m-%d
, which is the ISO 8601 date
format.
This is a GNU extension following an ISO C99 extension to
strftime
.
%g
00
through 99
).
Note: Currently, this is not fully implemented. 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.
%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.
%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.
%M
0
through 59
).
Leading zeroes are permitted but not required.
%OM
%M
but using the locale's alternative numeric symbols.
%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 60
).
Leading zeroes are permitted but not required.
Note: The Unix specification says the upper bound on this value
is 61
, a result of a decision to allow double leap seconds. You
will not see the value 61
because no minute has more than one
leap second, but the myth persists.
%OS
%S
but using the locale's alternative numeric symbols.
%T
%H:%M:%S
in this place.
%u
1
through
7
), Monday being 1
.
Leading zeroes are permitted but not required.
Note: Currently, this is not fully implemented. 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.
%V
1
through 53
).
Leading zeroes are permitted but not required.
Note: Currently, this is not fully implemented. 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: Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in tm is set.
%Ow
%w
but using the locale's alternative numeric symbols.
%W
0
through 53
).
Leading zeroes are permitted but not required.
Note: Currently, this is not fully implemented. The format is
recognized, input is consumed but no field in tm is set.
%OW
%W
but using the locale's alternative numeric symbols.
%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.
Note that it is 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 format 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 function returns a pointer to the first character it was unable to
process. If the input string contains more characters than required by
the format string the return value points right after the last consumed
input character. If the whole input string is consumed the return value
points to the NULL
byte at the end of the string. If an error
occurs, i.e. strptime
fails to match all of the format string,
the function returns NULL
.
The specification of the function in the XPG standard is rather vague, leaving out a few important pieces of information. Most importantly, it does not specify what happens to those elements of tm which are not directly initialized by the different formats. The 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, you
should prepare the tm structure you pass. Normally this will mean
initializing all values are to zero. Alternatively, you can set all
fields to values like INT_MAX
, allowing you 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 you want to find out whether a
certain field in tm was initialized by the function call.
struct tm
value with several consecutive
strptime
calls. A useful application of this is e.g. the parsing
of two separate strings, one containing date information and the other
time information. By parsing one after the other without clearing the
structure in-between, you can construct a complete broken-down time.
The following example shows a function which parses a string which is contains 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.