<<< Previous Home Next >>>
The Open Group Base Specifications Issue 8
IEEE Std 1003.1-2024
Copyright © 2001-2024 The IEEE and The Open Group

NAME

strptime — date and time conversion

SYNOPSIS

[XSI] [Option Start] #include <time.h>

char *strptime(const char *restrict buf, const char *restrict format,
       struct tm *restrict tm); [Option End]

DESCRIPTION

The strptime() function shall convert the character string pointed to by buf to values which are stored in the tm structure pointed to by tm, using the format specified by format.

The application shall ensure that the format is a character string, beginning and ending in its initial shift state, if any. The format is composed of zero or more directives. Each directive is composed of one of the following: one or more white-space bytes; an ordinary character (neither '%' nor a white-space byte); or a conversion specification.

Each conversion specification is introduced by the '%' character after which the following appear in sequence:

The conversions are determined using the LC_TIME category of the current locale. The application shall ensure that there are white-space bytes or other non-alphanumeric bytes between any two conversion specifications unless all of the adjacent conversion specifications convert a known, fixed number of characters. In the following list, the maximum number of characters scanned (excluding the one matching the next directive) is as follows:

The following conversion specifiers are supported.

The results are unspecified if a modifier is specified with a flag or with a minimum field width, or if a field width is specified for any conversion specifier other than C, F, G, Y, or Z.

a
The day of the week, using the locale's weekday names; either the abbreviated or full name can be specified. The tm_wday member of the tm structure pointed to by tm shall be set to the corresponding day of the week number (Sunday=0).
A
Equivalent to %a.
b
The month, using the locale's month names; either the abbreviated or full version of either the default or the alternative month name can be specified. The tm_mon member of the tm structure pointed to by tm shall be set to the corresponding month number.
B
Equivalent to %b.
c
Replaced by the locale's appropriate date and time representation. The members of the tm structure pointed to by tm shall be set as specified for the conversions present in the locale's d_t_fmt value.
C
All but the last two digits of the year {2}; leading zeros shall be permitted but shall not be required. A leading '+' or '-' character shall be permitted before any leading zeros but shall not be required. The tm_year member of the tm structure pointed to by tm shall be set to the number formed by appending the last two digits of the year to these digits, minus 1900. If a y conversion is also performed, the last two digits of the year shall be those processed by the y conversion; otherwise, they shall be 00.
d
The day of the month [01,31]; leading zeros shall be permitted but shall not be required. The tm_mday member of the tm structure pointed to by tm shall be set to this number.
D
Equivalent to %m/%d/%y.
e
Equivalent to %d.
F
This specifier is similar to %Y-%m-%d where the characters up to the first <hyphen-minus> separator shall be converted as for %Y but with unlimited field width, the characters between the two <hyphen-minus> separators shall be converted as for %m, and the characters after the last <hyphen-minus> separator shall be converted as for %d. If a field width is specified, each of the %Y, %m, and %d conversions shall not convert any characters past the overall %F field width. The members of the tm structure pointed to by tm shall be set as specified for the Y, m, and d conversions.
g
The last 2 digits of the week-based year (see below) as a decimal number (for example, 77). Leading zeros shall be permitted but shall not be required. A leading '+' or '-' character shall be permitted before any leading zeros but shall not be required. The effect of this year, if any, on the tm structure pointed to by tm is unspecified.
G
The week-based year (see below) as a decimal number (for example, 1977). Leading zeros shall be permitted but shall not be required. A leading '+' or '-' character shall be permitted before any leading zeros but shall not be required. The effect of this year, if any, on the tm structure pointed to by tm is unspecified.
h
Equivalent to %b.
H
The hour (24-hour clock) [00,23]; leading zeros shall be permitted but shall not be required. The tm_hour member of the tm structure pointed to by tm shall be set to this number.
I
The hour (12-hour clock) [01,12]; leading zeros shall be permitted but shall not be required. If a p conversion is also performed, the tm_hour member of the tm structure pointed to by tm shall be set to the hour, by the 24-hour clock, corresponding to the combined results of the I and p conversions. If a p conversion is not also performed, the behavior is unspecified.
j
The day number of the year [001,366]; leading zeros shall be permitted but shall not be required. The tm_yday member of the tm structure pointed to by tm shall be set to this number minus 1.
m
The month number [01,12]; leading zeros shall be permitted but shall not be required. The tm_mon member of the tm structure pointed to by tm shall be set to this number minus 1.
M
The minute [00,59]; leading zeros shall be permitted but shall not be required. The tm_min member of the tm structure pointed to by tm shall be set to this number.
n
Any white-space bytes.
p
The locale's equivalent of a.m. or p.m. If an I conversion is also performed, the tm_hour member of the tm structure pointed to by tm shall be set as specified for the I conversion; otherwise, the behavior is unspecified.
r
12-hour clock time, if the 12-hour format is supported in the locale (see XBD 7.3.5 LC_TIME ); in the POSIX locale, this shall be equivalent to %I:%M:%S %p. The members of the tm structure pointed to by tm shall be set as specified for the conversions present in the locale's t_fmt_ampm value.
R
Equivalent to %H:%M.
s
The number of seconds since the Epoch as a decimal number (see XBD 4.19 Seconds Since the Epoch ); leading zeros shall be permitted but shall not be required. The effect of this number, if any, on the tm structure pointed to by tm is unspecified.
S
The seconds [00,60]; leading zeros shall be permitted but shall not be required. The tm_sec member of the tm structure pointed to by tm shall be set to this number.
t
Any white-space bytes.
T
Equivalent to %H:%M:%S.
u
The weekday as a decimal number [1,7], with 1 representing Monday. The tm_wday member of the tm structure pointed to by tm shall be set to this number modulo 7.
U
The week number of the year (Sunday as the first day of the week) as a decimal number [00,53]; leading zeros shall be permitted but shall not be required. The effect of this week number, if any, on the tm structure pointed to by tm is unspecified.
V
The week number of the week-based year (see below) as a decimal number [01,53]. Leading zeros shall be permitted but shall not be required. The effect of this week number, if any, on the tm structure pointed to by tm is unspecified.
w
The weekday as a decimal number [0,6], with 0 representing Sunday. The tm_wday member of the tm structure pointed to by tm shall be set to this number.
W
The week number of the year (Monday as the first day of the week) as a decimal number [00,53]; leading zeros shall be permitted but shall not be required. The effect of this week number, if any, on the tm structure pointed to by tm is unspecified.
x
The date, using the locale's date format. The members of the tm structure pointed to by tm shall be set as specified for the conversions present in the locale's d_fmt value.
X
The time, using the locale's time format. The members of the tm structure pointed to by tm shall be set as specified for the conversions present in the locale's t_fmt value.
y
The last two digits of the year; leading zeros shall be permitted but shall not be required. A leading '+' or '-' character shall be permitted before any leading zeros but shall not be required. If a C conversion is not also performed, values in the range [69,99] shall refer to years 1969 to 1999 inclusive and values in the range [00,68] shall refer to years 2000 to 2068 inclusive. If a C conversion is also performed, the tm_year member of the tm structure pointed to by tm shall be set as specified for the C conversion; otherwise, the tm_year member shall be set to the calculated year minus 1900.
Note:
It is expected that in a future version of this standard the default century inferred from a 2-digit year will change. (This would apply to all commands accepting a 2-digit year as input.)
Y
The full year {4}; leading zeros shall be permitted but shall not be required. A leading '+' or '-' character shall be permitted before any leading zeros but shall not be required. The tm_year member of the tm structure pointed to by tm shall be set to this number minus 1900.
z
The offset from UTC in the ISO 8601:2019 standard format (+hhmm or -hhmm). For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich). The effect of this offset, if any, on the tm structure pointed to by tm is unspecified.
Z
The timezone name. If this name matches the name pointed to by tzname[1], and the names pointed to by tzname[0] and tzname[1] differ, then the tm_isdst member of the tm structure pointed to by tm shall be set to 1. Otherwise, if this name matches the name pointed to by tzname[0] then the tm_isdst member of the tm structure pointed to by tm shall be set to 0. The tm_zone and tm_gmtoff members of the structure may also be set in an unspecified manner. Members other than tm_isdst, tm_zone, and tm_gmtoff may be affected if an s conversion is also performed but shall otherwise not be affected.
%
Replaced by %.
Modified Conversion Specifiers

Some conversion specifiers can be modified by the E and O modifier characters to indicate that an alternative format or specification should be used rather than the one normally used by the unmodified conversion specifier. If the alternative format or specification does not exist in the current locale, the behavior shall be as if the unmodified conversion specification were used.

%Ec
The locale's alternative appropriate date and time representation.
%EC
The name of the base year (period) in the locale's alternative representation.
%Ex
The locale's alternative date representation.
%EX
The locale's alternative time representation.
%Ey
The offset from %EC (year only) in the locale's alternative representation.
%EY
The full alternative year representation.
%Ob
Equivalent to %b.
%OB
Equivalent to %b.
%Od
The day of the month using the locale's alternative numeric symbols; leading zeros shall be permitted but shall not be required.
%Oe
Equivalent to %Od.
%Oh
Equivalent to %b.
%OH
The hour (24-hour clock) using the locale's alternative numeric symbols.
%OI
The hour (12-hour clock) using the locale's alternative numeric symbols.
%Om
The month using the locale's alternative numeric symbols.
%OM
The minutes using the locale's alternative numeric symbols.
%OS
The seconds using the locale's alternative numeric symbols.
%OU
The week number of the year (Sunday as the first day of the week) using the locale's alternative numeric symbols.
%OV
The same as %V but using the locale's alternative numeric symbols.
%Ow
The number of the weekday (Sunday=0) using the locale's alternative numeric symbols.
%OW
The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols.
%Oy
The year (offset from %C) using the locale's alternative numeric symbols.

%g, %G, and %V convert values according to the ISO 8601:2019 standard week-based year. In this system, weeks begin on a Monday and week 1 of the week-based year is the week that includes January 4th, which is also the week that includes the first Thursday of the year, and is also the first week that contains at least four days in the year. If the first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding week-based year (thus, the string "1998 53 6" with format specifier "%G %V %u" represents Saturday 2nd January 1999). If December 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of the following week-based year (thus, the string "1998 01 2" with format specifier "%G %V %u" represents Tuesday 30th December 1997).

A conversion specification composed of white-space bytes is executed by scanning input up to the first non-white-space byte (which remains unscanned), or until no more characters can be scanned.

A conversion specification that is an ordinary character is executed by scanning the next character from the buffer. If the character scanned from the buffer differs from the one comprising the directive, the directive fails, and the differing and subsequent characters remain unscanned.

A series of conversion specifications composed of %n, %t, white-space bytes, or any combination is executed by scanning up to the first non-white-space byte (which remains unscanned), or until no more characters can be scanned.

Any other conversion specification is executed by scanning characters until a character matching the next directive is scanned, or until no more characters can be scanned. These characters, except the one matching the next directive, are then compared to the locale values associated with the conversion specifier. If a match is found, values for the affected tm structure members are set as specified in the description of the conversion specification. Case is ignored when matching items in buf such as month or weekday names. If no match is found, strptime() fails and no more characters are scanned.

RETURN VALUE

Upon successful completion, strptime() shall return a pointer to the character following the last character parsed. Otherwise, a null pointer shall be returned.

ERRORS

No errors are defined.

The following sections are informative.

EXAMPLES

Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds

The following example demonstrates the use of strptime() to convert a string into broken-down time. The broken-down time is then converted into seconds since the Epoch using mktime().

#include <time.h>
...


struct tm tm;
time_t t;


if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
    /* Handle error */;


printf("year: %d; month: %d; day: %d;\n",
        tm.tm_year, tm.tm_mon, tm.tm_mday);
printf("hour: %d; minute: %d; second: %d\n",
        tm.tm_hour, tm.tm_min, tm.tm_sec);
printf("week day: %d; year day: %d\n", tm.tm_wday, tm.tm_yday);


tm.tm_isdst = -1;      /* Not set by strptime(); tells mktime()
                          to determine whether daylight saving time
                          is in effect */
t = mktime(&tm);
if (t == -1)
    /* Handle error */;
printf("seconds since the Epoch: %ld\n", (long) t);"

APPLICATION USAGE

Several "equivalent to" formats and the special processing of white-space characters are provided in order to ease the use of identical format strings for strftime() and strptime().

It should be noted that dates constructed by the strftime() function with the %Y or %C%y conversion specifiers may have values larger than 9999. If the strptime() function is used to read such values using %C%y or %Y, the year values will be truncated to four digits. Applications should use %+w%y or %+xY with w and x set large enough to contain the full value of any years that will be printed or scanned.

The effect of the s conversion is unspecified because existing implementations differ in behavior. Some do a conversion equivalent to gmtime(), ignoring all available timezone information; some do a conversion equivalent to localtime(), using the same timezone it would use and ignoring any timezone information provided by a z or Z conversion. Although none has been observed, there may be existing (or future) implementations that use timezone information provided by a z or Z conversion, although using the latter would not be reliable as timezone names are often ambiguous. Applications that need to convert a seconds since the Epoch value to a tm structure should call gmtime() or localtime() (or their thread-safe equivalents) directly.

The effect of the z conversion is unspecified because existing implementations differ in behavior. Some just use it to set the tm_gmtoff member of the tm structure; some use the value to adjust the other field members to represent UTC, convert the resulting time to a seconds since the Epoch value, and then convert back to a tm structure by the equivalent of localtime(). An application that needs either of these behaviors should perform the necessary processing explicitly itself.

Although the Z conversion might be expected to set the tm_zone member of the tm structure, no existing implementation has been found that sets it. Applications that need it set should set it explicitly after calling strptime().

See also the APPLICATION USAGE section in strftime .

It is unspecified whether multiple calls to strptime() using the same tm structure will update the current contents of the structure or overwrite all contents of the structure. Conforming applications should make a single call to strptime() with a format and all data needed to completely specify the date and time being converted.

RATIONALE

See the RATIONALE section for strftime .

FUTURE DIRECTIONS

None.

SEE ALSO

fprintf , fscanf , strftime , time

XBD <time.h>

CHANGE HISTORY

First released in Issue 4.

Issue 5

Moved from ENHANCED I18N to BASE.

The [ENOSYS] error is removed.

The exact meaning of the %y and %Oy specifiers is clarified in the DESCRIPTION.

Issue 6

The Open Group Corrigendum U033/5 is applied. The %r specifier description is reworded.

The normative text is updated to avoid use of the term "must" for application requirements.

The restrict keyword is added to the strptime() prototype for alignment with the ISO/IEC 9899:1999 standard.

The Open Group Corrigendum U047/2 is applied.

The DESCRIPTION is updated to use the terms "conversion specifier" and "conversion specification" for consistency with strftime().

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/133 is applied, adding the example to the EXAMPLES section.

Issue 7

Austin Group Interpretation 1003.1-2001 #041 is applied, updating the DESCRIPTION and APPLICATION USAGE sections.

Austin Group Interpretation 1003.1-2001 #163 is applied.

SD5-XSH-ERN-67 is applied, correcting the APPLICATION USAGE to remove the impression that %Y is 4-digit years.

POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0345 [920] and XSH/TC2-2008/0346 [919] are applied.

Issue 8

Austin Group Defect 169 is applied, adding the s conversion.

Austin Group Defects 258 and 1166 are applied, adding the Ob, OB, and Oh modified conversions.

Austin Group Defect 879 is applied, adding the F, g, G, u, V, z, and Z conversions and the OV modified conversion, and adding a statement to the week number conversions that their effect on the tm structure pointed to by tm is unspecified.

Austin Group Defect 1163 is applied, clarifying the handling of white space in the format string.

Austin Group Defect 1307 is applied, changing the r conversion in relation to locales that do not support the 12-hour clock format.

Austin Group Defect 1562 is applied, clarifying that it is the application's responsibility to ensure that the format is a character string, beginning and ending in its initial shift state, if any.

Austin Group Defect 1727 is applied, clarifying which members of the tm structure are updated by each conversion.

End of informative text.

 

return to top of page
UNIX® is a registered Trademark of The Open Group.
POSIX™ is a Trademark of The IEEE.
Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]
<<< Previous Home Next >>>