path: root/man-pages-posix-2017/man3p/strptime.3p

'\" et
.TH STRPTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
strptime
\(em date and time conversion
.SH SYNOPSIS
.LP
.nf
#include <time.h>
.P
char *strptime(const char *restrict \fIbuf\fP, const char *restrict \fIformat\fP,
    struct tm *restrict \fItm\fP);
.fi
.SH DESCRIPTION
The
\fIstrptime\fR()
function shall convert the character string pointed to by
.IR buf
to values which are stored in the
.BR tm
structure pointed to by
.IR tm ,
using the format specified by
.IR format .
.P
The format is composed of zero or more directives. Each directive is
composed of one of the following: one or more white-space characters
(as specified by
\fIisspace\fR());
an ordinary character (neither
.BR '%' 
nor a white-space character); or a conversion specification.
.P
Each conversion specification is introduced by the
.BR '%' 
character after which the following appear in sequence:
.IP " *" 4
An optional flag, the zero character (\c
.BR '0' )
or the
<plus-sign>
character (\c
.BR '+' ),
which is ignored.
.IP " *" 4
An optional field width. If a field width is specified, it shall be
interpreted as a string of decimal digits that will determine the maximum
number of bytes converted for the conversion rather than the number of
bytes specified below in the description of the conversion specifiers.
.IP " *" 4
An optional
.BR E
or
.BR O
modifier.
.IP " *" 4
A terminating conversion specifier character that indicates the type of
conversion to be applied.
.P
The conversions are determined using the
.IR LC_TIME
category of the current locale. The application shall ensure that
there is white-space or other non-alphanumeric characters 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:
.IP " *" 4
If a maximum field width is specified, then that number
.IP " *" 4
Otherwise, the pattern
.BR \(dq{x}\(dq 
indicates that the maximum is
.IR x
.IP " *" 4
Otherwise, the pattern
.BR \(dq[x,y]\(dq 
indicates that the value shall fall within the range given (both bounds
being inclusive), and the maximum number of characters scanned shall be
the maximum required to represent any value in the range without leading
zeros and without a leading
<plus-sign>
.P
The following conversion specifiers are supported.
.P
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
.BR C
or
.BR Y .
.IP "\fRa\fR" 8
The day of the week, using the locale's weekday names; either the
abbreviated or full name may be specified.
.IP "\fRA\fR" 8
Equivalent to
.BR %a .
.IP "\fRb\fR" 8
The month, using the locale's month names; either the abbreviated or
full name may be specified.
.IP "\fRB\fR" 8
Equivalent to
.BR %b .
.IP "\fRc\fR" 8
Replaced by the locale's appropriate date and time representation.
.IP "\fRC\fR" 8
All but the last two digits of the year {2}; leading zeros shall be
permitted but shall not be required. A leading
.BR '+' 
or
.BR '\-' 
character shall be permitted before any leading zeros but shall not
be required.
.IP "\fRd\fR" 8
The day of the month [01,31]; leading zeros shall be permitted but shall
not be required.
.IP "\fRD\fR" 8
The date as
.BR %m /\c
.BR %d /\c
.BR %y .
.IP "\fRe\fR" 8
Equivalent to
.BR %d .
.IP "\fRh\fR" 8
Equivalent to
.BR %b .
.IP "\fRH\fR" 8
The hour (24-hour clock) [00,23]; leading zeros shall be permitted but
shall not be required.
.IP "\fRI\fR" 8
The hour (12-hour clock) [01,12]; leading zeros shall be permitted but
shall not be required.
.IP "\fRj\fR" 8
The day number of the year [001,366]; leading zeros shall be permitted
but shall not be required.
.IP "\fRm\fR" 8
The month number [01,12]; leading zeros shall be permitted but shall
not be required.
.IP "\fRM\fR" 8
The minute [00,59]; leading zeros shall be permitted but shall not
be required.
.IP "\fRn\fR" 8
Any white space.
.IP "\fRp\fR" 8
The locale's equivalent of a.m. or p.m.
.IP "\fRr\fR" 8
12-hour clock time using the AM/PM notation if
.BR t_fmt_ampm
is not an empty string in the
.IR LC_TIME
portion of the current locale; in the POSIX locale, this shall
be equivalent to
.BR %I :\c
.BR %M :\c
.BR %S
.BR %p .
.IP "\fRR\fR" 8
The time as
.BR %H :\c
.BR %M .
.IP "\fRS\fR" 8
The seconds [00,60]; leading zeros shall be permitted but shall
not be required.
.IP "\fRt\fR" 8
Any white space.
.IP "\fRT\fR" 8
The time as
.BR %H :\c
.BR %M :\c
.BR %S .
.IP "\fRU\fR" 8
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.
.IP "\fRw\fR" 8
The weekday as a decimal number [0,6], with 0 representing Sunday.
.IP "\fRW\fR" 8
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.
.IP "\fRx\fR" 8
The date, using the locale's date format.
.IP "\fRX\fR" 8
The time, using the locale's time format.
.IP "\fRy\fR" 8
The last two digits of the year. When
.IR format
contains neither a
.BR C
conversion specifier nor a
.BR Y
conversion specifier, 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; leading zeros shall be permitted but shall
not be required. A leading
.BR '+' 
or
.BR '\-' 
character shall be permitted before any leading zeros but shall not
be required.
.RS 8 
.TP 10
.BR 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.)
.P
.RE
.IP "\fRY\fR" 8
The full year {4}; leading zeros shall be permitted but shall
not be required. A leading
.BR '+' 
or
.BR '\-' 
character shall be permitted before any leading zeros but shall not
be required.
.IP "\fR%\fP" 8
Replaced by
.BR % .
.SS "Modified Conversion Specifiers"
.P
Some conversion specifiers can be modified by the
.BR E
and
.BR 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.
.IP "\fR%Ec\fR" 8
The locale's alternative appropriate date and time representation.
.IP "\fR%EC\fR" 8
The name of the base year (period) in the locale's alternative
representation.
.IP "\fR%Ex\fR" 8
The locale's alternative date representation.
.IP "\fR%EX\fR" 8
The locale's alternative time representation.
.IP "\fR%Ey\fR" 8
The offset from
.BR %EC
(year only) in the locale's alternative representation.
.IP "\fR%EY\fR" 8
The full alternative year representation.
.IP "\fR%Od\fR" 8
The day of the month using the locale's alternative numeric symbols;
leading zeros shall be permitted but shall not be required.
.IP "\fR%Oe\fR" 8
Equivalent to
.BR %Od .
.IP "\fR%OH\fR" 8
The hour (24-hour clock) using the locale's alternative numeric
symbols.
.IP "\fR%OI\fR" 8
The hour (12-hour clock) using the locale's alternative numeric
symbols.
.IP "\fR%Om\fR" 8
The month using the locale's alternative numeric symbols.
.IP "\fR%OM\fR" 8
The minutes using the locale's alternative numeric symbols.
.IP "\fR%OS\fR" 8
The seconds using the locale's alternative numeric symbols.
.IP "\fR%OU\fR" 8
The week number of the year (Sunday as the first day of the week) using
the locale's alternative numeric symbols.
.IP "\fR%Ow\fR" 8
The number of the weekday (Sunday=0) using the locale's alternative
numeric symbols.
.IP "\fR%OW\fR" 8
The week number of the year (Monday as the first day of the week) using
the locale's alternative numeric symbols.
.IP "\fR%Oy\fR" 8
The year (offset from
.BR %C )
using the locale's alternative numeric symbols.
.P
A conversion specification composed of white-space characters is
executed by scanning input up to the first character that is not
white-space (which remains unscanned), or until no more characters can
be scanned.
.P
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.
.P
A series of conversion specifications composed of
.BR %n ,
.BR %t ,
white-space characters, or any combination is executed by scanning up
to the first character that is not white space (which remains
unscanned), or until no more characters can be scanned.
.P
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 appropriate
.BR tm
structure members are set to values corresponding to the locale
information. Case is ignored when matching items in
.IR buf
such as month or weekday names. If no match is found,
\fIstrptime\fR()
fails and no more characters are scanned.
.SH "RETURN VALUE"
Upon successful completion,
\fIstrptime\fR()
shall return a pointer to the character following the last character
parsed. Otherwise, a null pointer shall be returned.
.SH ERRORS
No errors are defined.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
.SS "Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds"
.P
The following example demonstrates the use of
\fIstrptime\fR()
to convert a string into broken-down time. The broken-down time is then
converted into seconds since the Epoch using
\fImktime\fR().
.sp
.RS 4
.nf

#include <time.h>
\&...
.P
struct tm tm;
time_t t;
.P
if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL)
    /* Handle error */;
.P
printf("year: %d; month: %d; day: %d;\en",
        tm.tm_year, tm.tm_mon, tm.tm_mday);
printf("hour: %d; minute: %d; second: %d\en",
        tm.tm_hour, tm.tm_min, tm.tm_sec);
printf("week day: %d; year day: %d\en", tm.tm_wday, tm.tm_yday);
.P
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\en", (long) t);"
.fi
.P
.RE
.SH "APPLICATION USAGE"
Several ``equivalent to'' formats and the special processing of
white-space characters are provided in order to ease the use of
identical
.IR format
strings for
\fIstrftime\fR()
and
\fIstrptime\fR().
.P
It should be noted that dates constructed by the
\fIstrftime\fR()
function with the
.BR %Y
or
.BR %C%y
conversion specifiers may have values larger than 9\|999. If the
\fIstrptime\fR()
function is used to read such values using
.BR %C%y
or
.BR %Y ,
the year values will be truncated to four digits. Applications should use
.BR %+ \c
.IR w \c
.BR %y
or
.BR %+ \c
.IR x \c
.BR Y
with
.IR w
and
.IR x
set large enough to contain the full value of any years that will be
printed or scanned.
.P
See also the APPLICATION USAGE section in
.IR "\fIstrftime\fR\^(\|)".
.P
It is unspecified whether multiple calls to
\fIstrptime\fR()
using the same
.BR 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
\fIstrptime\fR()
with a format and all data needed to completely specify the date and
time being converted.
.SH RATIONALE
See the RATIONALE section for
.IR "\fIstrftime\fR\^(\|)".
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIfprintf\fR\^(\|)",
.IR "\fIfscanf\fR\^(\|)",
.IR "\fIstrftime\fR\^(\|)",
.IR "\fItime\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<time.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .