summaryrefslogtreecommitdiffstats
path: root/man3/strptime.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/strptime.3414
1 files changed, 414 insertions, 0 deletions
diff --git a/man3/strptime.3 b/man3/strptime.3
new file mode 100644
index 0000000..6dd0590
--- /dev/null
+++ b/man3/strptime.3
@@ -0,0 +1,414 @@
+'\" t
+.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+strptime \- convert a string representation of time to a time tm structure
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */"
+.B #include <time.h>
+.PP
+.BI "char *strptime(const char *restrict " s ", const char *restrict " format ,
+.BI " struct tm *restrict " tm );
+.fi
+.SH DESCRIPTION
+The
+.BR strptime ()
+function is the converse of
+.BR strftime (3);
+it converts the character string pointed to by
+.I s
+to values which are stored in the
+"broken-down time"
+structure pointed to by
+.IR tm ,
+using the format specified by
+.IR format .
+.PP
+The broken-down time structure
+.I tm
+is described in
+.BR tm (3type).
+.PP
+The
+.I format
+argument
+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 the name of a day of the week or a 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 name of the day of the week 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\[en]99).
+.TP
+.BR %d " or " %e
+The day of month (1\[en]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\[en]23).
+.TP
+.B %I
+The hour on a 12-hour clock (1\[en]12).
+.TP
+.B %j
+The day number in the year (1\[en]366).
+.TP
+.B %m
+The month number (1\[en]12).
+.TP
+.B %M
+The minute (0\[en]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
+.I t_fmt_ampm
+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\[en]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\[en]53).
+The first Sunday of January is the first day of week 1.
+.TP
+.B %w
+The ordinal number of the day of the week (0\[en]6), with Sunday = 0.
+.TP
+.B %W
+The week number with Monday the first day of the week (0\[en]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\[en]99).
+When a century is not otherwise specified, values in the range 69\[en]99 refer
+to years in the twentieth century (1969\[en]1999); values in the
+range 00\[en]68 refer to years in the twenty-first century (2000\[en]2068).
+.TP
+.B %Y
+The year, including century (for example, 1991).
+.PP
+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.
+.PP
+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.
+.PP
+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 ordinal number of the day of the week (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.
+.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 ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR strptime ()
+T} Thread safety MT-Safe env locale
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SUSv2.
+.SH NOTES
+In principle, this function does not initialize
+.I tm
+but
+stores only the values specified.
+This means that
+.I tm
+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 \[aq]n\[aq] and \[aq]t\[aq] specifications) was not handled,
+.\" no \[aq]E\[aq] and \[aq]O\[aq] locale modifier characters were accepted,
+.\" and the \[aq]C\[aq] specification was a synonym for the \[aq]c\[aq] specification.
+.PP
+The \[aq]y\[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\[en]2049 by glibc 2.0.
+It is taken to be a year in
+1969\[en]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
+.I tm
+is changed.)
+This leads to
+.TP
+.B %F
+Equivalent to
+.BR %Y\-%m\-%d ,
+the ISO 8601 date format.
+.TP
+.B %g
+The year corresponding to the ISO week number, but without the century
+(0\[en]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\[en]7, where Monday = 1).
+.TP
+.B %V
+The ISO 8601:1988 week number as a decimal number (1\[en]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 timezone specification.
+.TP
+.B %Z
+The timezone name.
+.PP
+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, 1970-01-01 00:00:00 +0000 (UTC).
+Leap seconds are not counted unless leap second support is available.
+.PP
+The glibc implementation does not require whitespace between
+two field descriptors.
+.SH EXAMPLES
+The following example demonstrates the use of
+.BR strptime ()
+and
+.BR strftime (3).
+.PP
+.\" SRC BEGIN (strptime.c)
+.EX
+#define _XOPEN_SOURCE
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+\&
+int
+main(void)
+{
+ struct tm tm;
+ char buf[255];
+\&
+ memset(&tm, 0, sizeof(tm));
+ 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);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR time (2),
+.BR getdate (3),
+.BR scanf (3),
+.BR setlocale (3),
+.BR strftime (3)