mirror of https://github.com/mkerrisk/man-pages
299 lines
9.2 KiB
Plaintext
299 lines
9.2 KiB
Plaintext
|
.\" 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 .
|