diff options
Diffstat (limited to 'man/man3/strptime.3')
| -rw-r--r-- | man/man3/strptime.3 | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/man/man3/strptime.3 b/man/man3/strptime.3 new file mode 100644 index 0000000..ba6c383 --- /dev/null +++ b/man/man3/strptime.3 @@ -0,0 +1,413 @@ +'\" 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 2024-05-02 "Linux man-pages (unreleased)" +.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> +.P +.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 . +.P +The broken-down time structure +.I tm +is described in +.BR tm (3type). +.P +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. +.P +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. +.P +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). +.P +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. +.P +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. +.P +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 +.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. +.\" .P +.\" 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. +.\" .P +.\" 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. +.P +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. +.P +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. +.P +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). +.P +.\" 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) |