mirror of https://github.com/mkerrisk/man-pages
412 lines
11 KiB
Groff
412 lines
11 KiB
Groff
.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08
|
|
.\" Modified, aeb, 2000-04-07
|
|
.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25
|
|
.\" Modified, aeb, 2001-08-31
|
|
.\" Modified, wharms 2001-11-12, remark on white space and example
|
|
.\"
|
|
.TH STRPTIME 3 2001-11-12 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
strptime \- convert a string representation of time to a time tm structure
|
|
.SH SYNOPSIS
|
|
.BR "#define _XOPEN_SOURCE" " /* glibc2 needs this */"
|
|
.br
|
|
.B #include <time.h>
|
|
.sp
|
|
.BI "char *strptime(const char *" s ", const char *" format ,
|
|
.BI "struct tm *" tm );
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR strptime ()
|
|
function is the converse function to
|
|
.BR strftime (3)
|
|
and converts the character string pointed to by
|
|
.I s
|
|
to values which are stored in the
|
|
.I tm
|
|
structure pointed to by
|
|
.IR tm ,
|
|
using the format specified by
|
|
.IR format .
|
|
Here
|
|
.I format
|
|
is a character string that consists of field descriptors and text characters,
|
|
reminiscent of
|
|
.BR scanf (3).
|
|
Each field descriptor consists of a
|
|
.B %
|
|
character followed by another character that specifies the replacement
|
|
for the field descriptor.
|
|
All other characters in the
|
|
.I format
|
|
string must have a matching character in the input string,
|
|
except for whitespace, which matches zero or more
|
|
whitespace characters in the input string.
|
|
There should be white\%space or other alphanumeric characters
|
|
between any two field descriptors.
|
|
.PP
|
|
The
|
|
.BR strptime ()
|
|
function processes the input string from left
|
|
to right.
|
|
Each of the three possible input elements (whitespace,
|
|
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.
|
|
.PP
|
|
The supported input field descriptors are listed below.
|
|
In case a text string (such as a weekday or month name)
|
|
is to be matched, the comparison is case insensitive.
|
|
In case a number is to be matched, leading zeros are
|
|
permitted but not required.
|
|
.TP
|
|
.B %%
|
|
The
|
|
.B %
|
|
character.
|
|
.TP
|
|
.BR %a " or " %A
|
|
The weekday name according to the current locale,
|
|
in abbreviated form or the full name.
|
|
.TP
|
|
.BR %b " or " %B " or " %h
|
|
The month name according to the current locale,
|
|
in abbreviated form or the full name.
|
|
.TP
|
|
.B %c
|
|
The date and time representation for the current locale.
|
|
.TP
|
|
.B %C
|
|
The century number (0-99).
|
|
.TP
|
|
.BR %d " or " %e
|
|
The day of month (1-31).
|
|
.TP
|
|
.B %D
|
|
Equivalent to
|
|
.BR %m/%d/%y .
|
|
(This is the American style date, very confusing
|
|
to non-Americans, especially since
|
|
.B %d/%m/%y
|
|
is widely used in Europe.
|
|
The ISO 8601 standard format is
|
|
.BR %Y-%m-%d .)
|
|
.TP
|
|
.B %H
|
|
The hour (0-23).
|
|
.TP
|
|
.B %I
|
|
The hour on a 12-hour clock (1-12).
|
|
.TP
|
|
.B %j
|
|
The day number in the year (1-366).
|
|
.TP
|
|
.B %m
|
|
The month number (1-12).
|
|
.TP
|
|
.B %M
|
|
The minute (0-59).
|
|
.TP
|
|
.B %n
|
|
Arbitrary whitespace.
|
|
.TP
|
|
.B %p
|
|
The locale's equivalent of AM or PM. (Note: there may be none.)
|
|
.TP
|
|
.B %r
|
|
The 12-hour clock time (using the locale's AM or PM).
|
|
In the POSIX locale equivalent to
|
|
.BR "%I:%M:%S %p" .
|
|
If \fIt_fmt_ampm\fP is empty in the
|
|
.B LC_TIME
|
|
part of the current locale
|
|
then the behavior is undefined.
|
|
.TP
|
|
.B %R
|
|
Equivalent to
|
|
.BR %H:%M .
|
|
.TP
|
|
.B %S
|
|
The second (0-60; 60 may occur for leap seconds;
|
|
earlier also 61 was allowed).
|
|
.TP
|
|
.B %t
|
|
Arbitrary whitespace.
|
|
.TP
|
|
.B %T
|
|
Equivalent to
|
|
.BR %H:%M:%S .
|
|
.TP
|
|
.B %U
|
|
The week number with Sunday the first day of the week (0-53).
|
|
The first Sunday of January is the first day of week 1.
|
|
.TP
|
|
.B %w
|
|
The weekday number (0-6) with Sunday = 0.
|
|
.TP
|
|
.B %W
|
|
The week number with Monday the first day of the week (0-53).
|
|
The first Monday of January is the first day of week 1.
|
|
.TP
|
|
.B %x
|
|
The date, using the locale's date format.
|
|
.TP
|
|
.B %X
|
|
The time, using the locale's time format.
|
|
.TP
|
|
.B %y
|
|
The year within century (0-99).
|
|
When a century is not otherwise specified, values in the range 69-99 refer
|
|
to years in the twentieth century (1969-1999); values in the
|
|
range 00-68 refer to years in the twenty-first century (2000-2068).
|
|
.TP
|
|
.B %Y
|
|
The year, including century (for example, 1991).
|
|
.LP
|
|
Some field descriptors can be modified by the E or O modifier characters
|
|
to indicate that an alternative format or specification should be used.
|
|
If the
|
|
alternative format or specification does not exist in the current locale, the
|
|
unmodified field descriptor is used.
|
|
.LP
|
|
The E modifier specifies that the input string may contain
|
|
alternative locale-dependent versions of the date and time representation:
|
|
.TP
|
|
.B %Ec
|
|
The locale's alternative date and time representation.
|
|
.TP
|
|
.B %EC
|
|
The name of the base year (period) in the locale's alternative representation.
|
|
.TP
|
|
.B %Ex
|
|
The locale's alternative date representation.
|
|
.TP
|
|
.B %EX
|
|
The locale's alternative time representation.
|
|
.TP
|
|
.B %Ey
|
|
The offset from
|
|
.B %EC
|
|
(year only) in the locale's alternative representation.
|
|
.TP
|
|
.B %EY
|
|
The full alternative year representation.
|
|
.LP
|
|
The O modifier specifies that the numerical input may be in an
|
|
alternative locale-dependent format:
|
|
.TP
|
|
.BR %Od " or " %Oe
|
|
The day of the month using the locale's alternative numeric symbols;
|
|
leading zeros are permitted but not required.
|
|
.TP
|
|
.B %OH
|
|
The hour (24-hour clock) using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %OI
|
|
The hour (12-hour clock) using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %Om
|
|
The month using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %OM
|
|
The minutes using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %OS
|
|
The seconds using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %OU
|
|
The week number of the year (Sunday as the first day of the week)
|
|
using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %Ow
|
|
The number of the weekday (Sunday=0) using the locale's alternative
|
|
numeric symbols.
|
|
.TP
|
|
.B %OW
|
|
The week number of the year (Monday as the first day of the week)
|
|
using the locale's alternative numeric symbols.
|
|
.TP
|
|
.B %Oy
|
|
The year (offset from
|
|
.BR %C )
|
|
using the locale's alternative numeric symbols.
|
|
.LP
|
|
The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP
|
|
as follows:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
struct tm {
|
|
int tm_sec; /* seconds */
|
|
int tm_min; /* minutes */
|
|
int tm_hour; /* hours */
|
|
int tm_mday; /* day of the month */
|
|
int tm_mon; /* month */
|
|
int tm_year; /* year */
|
|
int tm_wday; /* day of the week */
|
|
int tm_yday; /* day in the year */
|
|
int tm_isdst; /* daylight saving time */
|
|
};
|
|
.fi
|
|
.in
|
|
.SH "RETURN VALUE"
|
|
The return value of the function is a pointer to the first character
|
|
not processed in this function call.
|
|
In case the input string
|
|
contains more characters than required by the format string the return
|
|
value points right after the last consumed input character.
|
|
In case
|
|
the whole input string is consumed the return value points to the null
|
|
byte at the end of the string.
|
|
If
|
|
.BR strptime ()
|
|
fails to match all
|
|
of the format string and therefore an error occurred the function
|
|
returns NULL.
|
|
.SH "CONFORMING TO"
|
|
SUSv2, POSIX.1-2001.
|
|
.SH NOTES
|
|
.LP
|
|
In principle, this function does not initialize \fItm\fP but
|
|
only stores the values specified.
|
|
This means that \fItm\fP should be initialized before the call.
|
|
Details differ a bit between different Unix systems.
|
|
The glibc implementation does not touch those fields which are not
|
|
explicitly specified, except that it recomputes the
|
|
.I tm_wday
|
|
and
|
|
.I tm_yday
|
|
field if any of the year, month, or day elements changed.
|
|
.PP
|
|
This function is available since libc 4.6.8.
|
|
Linux libc4 and libc5 includes define the prototype unconditionally;
|
|
glibc2 includes provide a prototype only when
|
|
.B _XOPEN_SOURCE
|
|
or
|
|
.B _GNU_SOURCE
|
|
are defined.
|
|
.PP
|
|
Before libc 5.4.13 whitespace
|
|
(and the \(aqn\(aq and \(aqt\(aq specifications) was not handled,
|
|
no \(aqE\(aq and \(aqO\(aq locale modifier characters were accepted,
|
|
and the \(aqC\(aq specification was a synonym for the \(aqc\(aq specification.
|
|
.PP
|
|
The \(aqy\(aq (year in century) specification is taken to specify a year
|
|
in the 20th century by libc4 and libc5.
|
|
It is taken to be a year
|
|
in the range 1950-2049 by glibc 2.0.
|
|
It is taken to be a year in
|
|
1969-2068 since glibc 2.1.
|
|
.\" In libc4 and libc5 the code for %I is broken (fixed in glibc;
|
|
.\" %OI was fixed in glibc 2.2.4).
|
|
.SS Glibc Notes
|
|
For reasons of symmetry, glibc tries to support for
|
|
.BR strptime ()
|
|
the same format characters as for
|
|
.BR strftime (3).
|
|
(In most cases the corresponding fields are parsed, but no field in \fItm\fP
|
|
is changed.)
|
|
This leads to
|
|
.TP
|
|
.B %F
|
|
Equivalent to \fB%Y-%m-%d\fP, the ISO 8601 date format.
|
|
.TP
|
|
.B %g
|
|
The year corresponding to the ISO week number, but without the century
|
|
(0-99).
|
|
.TP
|
|
.B %G
|
|
The year corresponding to the ISO week number. (For example, 1991.)
|
|
.TP
|
|
.B %u
|
|
The day of the week as a decimal number (1-7, where Monday = 1).
|
|
.TP
|
|
.B %V
|
|
The ISO 8601:1988 week number as a decimal number (1-53).
|
|
If the week (starting on Monday) containing 1 January has four or more days
|
|
in the new year, then it is considered week 1.
|
|
Otherwise, it is the last week
|
|
of the previous year, and the next week is week 1.
|
|
.TP
|
|
.B %z
|
|
An RFC-822/ISO 8601 standard time zone specification.
|
|
.TP
|
|
.B %Z
|
|
The timezone name.
|
|
.LP
|
|
Similarly, because of GNU extensions to
|
|
.BR strftime (3),
|
|
.B %k
|
|
is accepted as a synonym for
|
|
.BR %H ,
|
|
and
|
|
.B %l
|
|
should be accepted
|
|
as a synonym for
|
|
.BR %I ,
|
|
and
|
|
.B %P
|
|
is accepted as a synonym for
|
|
.BR %p .
|
|
Finally
|
|
.TP
|
|
.B %s
|
|
The number of seconds since the Epoch,
|
|
that is, since 1970-01-01 00:00:00 UTC.
|
|
Leap seconds are not counted unless leap second support is available.
|
|
.LP
|
|
The glibc implementation does not require whitespace between
|
|
two field descriptors.
|
|
.SH EXAMPLE
|
|
The following example demonstrates the use of
|
|
.BR strptime ()
|
|
and
|
|
.BR strftime (3).
|
|
.sp
|
|
.nf
|
|
#define _XOPEN_SOURCE
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <time.h>
|
|
|
|
int
|
|
main(void)
|
|
{
|
|
struct tm tm;
|
|
char buf[255];
|
|
|
|
strptime("2001\-11\-12 18:31:01", "%Y\-%m\-%d %H:%M:%S", &tm);
|
|
strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
|
|
puts(buf);
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR time (2),
|
|
.BR getdate (3),
|
|
.BR scanf (3),
|
|
.BR setlocale (3),
|
|
.BR strftime (3),
|
|
.BR feature_test_macros (7)
|