path: root/man3p/strptime.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "STRPTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" strptime 
.SH NAME
strptime \- date and time conversion
.SH SYNOPSIS
.LP
\fB#include <time.h>
.br
.sp
char *strptime(const char *restrict\fP \fIbuf\fP\fB, const char *restrict\fP
\fIformat\fP\fB,
.br
\ \ \ \ \ \  struct tm *restrict\fP \fItm\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIstrptime\fP() function shall convert the character string pointed
to by \fIbuf\fP to values which are stored in the
\fBtm\fP structure pointed to by \fItm\fP, using the format specified
by \fIformat\fP.
.LP
The \fIformat\fP 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\fP()); an ordinary
character (neither
\fB'%'\fP nor a white-space character); or a conversion specification.
Each conversion specification is composed of a
\fB'%'\fP character followed by a conversion character which specifies
the replacement required. The application shall ensure
that there is white-space or other non-alphanumeric characters between
any two conversion specifications. The following conversion
specifications are supported:
.TP 7
\fB%a\fP
The day of the week, using the locale's weekday names; either the
abbreviated or full name may be specified.
.TP 7
\fB%A\fP
Equivalent to \fB%a\fP .
.TP 7
\fB%b\fP
The month, using the locale's month names; either the abbreviated
or full name may be specified.
.TP 7
\fB%B\fP
Equivalent to \fB%b\fP .
.TP 7
\fB%c\fP
Replaced by the locale's appropriate date and time representation.
.TP 7
\fB%C\fP
The century number [00,99]; leading zeros are permitted but not required.
.TP 7
\fB%d\fP
The day of the month [01,31]; leading zeros are permitted but not
required.
.TP 7
\fB%D\fP
The date as \fB%m\fP / \fB%d\fP / \fB%y\fP .
.TP 7
\fB%e\fP
Equivalent to \fB%d\fP .
.TP 7
\fB%h\fP
Equivalent to \fB%b\fP .
.TP 7
\fB%H\fP
The hour (24-hour clock) [00,23]; leading zeros are permitted but
not required.
.TP 7
\fB%I\fP
The hour (12-hour clock) [01,12]; leading zeros are permitted but
not required.
.TP 7
\fB%j\fP
The day number of the year [001,366]; leading zeros are permitted
but not required.
.TP 7
\fB%m\fP
The month number [01,12]; leading zeros are permitted but not required.
.TP 7
\fB%M\fP
The minute [00,59]; leading zeros are permitted but not required.
.TP 7
\fB%n\fP
Any white space.
.TP 7
\fB%p\fP
The locale's equivalent of a.m or p.m.
.TP 7
\fB%r\fP
12-hour clock time using the AM/PM notation if \fBt_fmt_ampm\fP is
not an empty string in the LC_TIME portion of the current
locale; in the POSIX locale, this shall be equivalent to \fB%I\fP
: \fB%M\fP : \fB%S\fP \fB%p\fP .
.TP 7
\fB%R\fP
The time as \fB%H\fP : \fB%M\fP .
.TP 7
\fB%S\fP
The seconds [00,60]; leading zeros are permitted but not required.
.TP 7
\fB%t\fP
Any white space.
.TP 7
\fB%T\fP
The time as \fB%H\fP : \fB%M\fP : \fB%S\fP .
.TP 7
\fB%U\fP
The week number of the year (Sunday as the first day of the week)
as a decimal number [00,53]; leading zeros are permitted but
not required.
.TP 7
\fB%w\fP
The weekday as a decimal number [0,6], with 0 representing Sunday;
leading zeros are permitted but not required.
.TP 7
\fB%W\fP
The week number of the year (Monday as the first day of the week)
as a decimal number [00,53]; leading zeros are permitted but
not required.
.TP 7
\fB%x\fP
The date, using the locale's date format.
.TP 7
\fB%X\fP
The time, using the locale's time format.
.TP 7
\fB%y\fP
The year within century. When a century is not otherwise specified,
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.  
.TP 7
\fBNote:\fP
.RS
It is expected that in a future version of IEEE\ Std\ 1003.1-2001
the default century inferred from a 2-digit year will
change. (This would apply to all commands accepting a 2-digit year
as input.)
.RE
.sp
.TP 7
\fB%Y\fP
The year, including the century (for example, 1988).
.TP 7
\fB%%\fP
Replaced by \fB%\fP .
.sp
.SS Modified Conversion Specifiers
.LP
Some conversion specifiers can be modified by the \fBE\fP and \fBO\fP
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.
.TP 7
\fB%Ec\fP
The locale's alternative appropriate date and time representation.
.TP 7
\fB%EC\fP
The name of the base year (period) in the locale's alternative representation.
.TP 7
\fB%Ex\fP
The locale's alternative date representation.
.TP 7
\fB%EX\fP
The locale's alternative time representation.
.TP 7
\fB%Ey\fP
The offset from \fB%EC\fP (year only) in the locale's alternative
representation.
.TP 7
\fB%EY\fP
The full alternative year representation.
.TP 7
\fB%Od\fP
The day of the month using the locale's alternative numeric symbols;
leading zeros are permitted but not required.
.TP 7
\fB%Oe\fP
Equivalent to \fB%Od\fP .
.TP 7
\fB%OH\fP
The hour (24-hour clock) using the locale's alternative numeric symbols.
.TP 7
\fB%OI\fP
The hour (12-hour clock) using the locale's alternative numeric symbols.
.TP 7
\fB%Om\fP
The month using the locale's alternative numeric symbols.
.TP 7
\fB%OM\fP
The minutes using the locale's alternative numeric symbols.
.TP 7
\fB%OS\fP
The seconds using the locale's alternative numeric symbols.
.TP 7
\fB%OU\fP
The week number of the year (Sunday as the first day of the week)
using the locale's alternative numeric symbols.
.TP 7
\fB%Ow\fP
The number of the weekday (Sunday=0) using the locale's alternative
numeric symbols.
.TP 7
\fB%OW\fP
The week number of the year (Monday as the first day of the week)
using the locale's alternative numeric symbols.
.TP 7
\fB%Oy\fP
The year (offset from \fB%C\fP ) using the locale's alternative numeric
symbols.
.sp
.LP
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.
.LP
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.
.LP
A series of conversion specifications composed of \fB%n\fP , \fB%t\fP
, 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.
.LP
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 \fBtm\fP structure members
are set to values corresponding to the locale information. Case is
ignored when matching items in \fIbuf\fP such as month or
weekday names. If no match is found, \fIstrptime\fP() fails and no
more characters are scanned.
.SH RETURN VALUE
.LP
Upon successful completion, \fIstrptime\fP() shall return a pointer
to the character following the last character parsed.
Otherwise, a null pointer shall be returned.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Several "equivalent to" formats and the special processing of white-space
characters are provided in order to ease the use of
identical \fIformat\fP strings for \fIstrftime\fP() and \fIstrptime\fP().
.LP
Applications should use \fB%Y\fP (4-digit years) in preference to
\fB%y\fP (2-digit years).
.LP
It is unspecified whether multiple calls to \fIstrptime\fP() using
the same \fBtm\fP 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\fP() with a format and all data needed to completely specify
the date and time being converted.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
The \fIstrptime\fP() function is expected to be mandatory in the next
version of this volume of
IEEE\ Std\ 1003.1-2001.
.SH SEE ALSO
.LP
\fIscanf\fP() , \fIstrftime\fP() , \fItime\fP()
, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .