diff options
Diffstat (limited to 'man3/strptime.3')
| -rw-r--r-- | man3/strptime.3 | 367 |
1 files changed, 367 insertions, 0 deletions
diff --git a/man3/strptime.3 b/man3/strptime.3 new file mode 100644 index 000000000..1c3baf869 --- /dev/null +++ b/man3/strptime.3 @@ -0,0 +1,367 @@ +.\" 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 +.B strptime() +function is the converse function to +.B strftime() +and converts the character string pointed to by +.I s +to values which are stored in the +.B 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 \fBstrptime()\fP 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 %m/%d/%y. (This is the American style date, very confusing +to non-Americans, especially since %d/%m/%y is widely used in Europe. +The ISO 8601 standard format is %Y-%m-%d.) +.TP +.BR %H +The hour (0-23). +.TP +.BR %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 %I:%M:%S %p. +If \fIt_fmt_ampm\fP is empty in the LC_TIME part of the current locale +then the behaviour is undefined. +.TP +.B %R +Equivalent to %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 %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 %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 %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 +.RS +.nf +.ne 12 +.ta 8n 16n 32n +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 */ +}; +.ta +.fi +.RE +.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 NUL +byte at the end of the string. If \fBstrptime()\fP fails to match all +of the format string and therefore an error occurred the function +returns \fBNULL\fP. +.SH "CONFORMING TO" +XPG4, SUSv2, POSIX 1003.1-2001. +.SH EXAMPLE +The following example demonstrates the use of \fBstrptime()\fP +and \fBstrftime()\fP. +.sp +.nf +.ne 12 +.ta 8n 16n +#include <stdio.h> +#include <time.h> + +int main() { + 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); + return 0; +} +.ta +.fi +.SH "GNU EXTENSIONS" +For reasons of symmetry, glibc tries to support for +.B strptime +the same format characters as for +.BR strftime. +(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 \fIstrftime\fP, +%k is accepted as a synonym for %H, and %l should be accepted +as a synonym for %I, and %P is accepted as a synonym for %p. +Finally +.TP +.B %s +The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC. +Leap seconds are not counted unless leap second support is available. +.LP +The GNU libc implementation does not require whitespace between +two field descriptors. +.SH NOTES +.LP +In principle, this function does not initialize \fBtm\fP but +only stores the values specified. +This means that \fBtm\fP should be initialized before the call. +Details differ a bit between different Unix systems. +The GNU libc implementation does not touch those fields which are not +explicitly specified, except that it recomputes the +.IR tm_wday +and +.IR 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 _XOPEN_SOURCE or _GNU_SOURCE +are defined. +.PP +Before libc 5.4.13 whitespace (and the 'n' and 't' specifications) +was not handled, no 'E' and 'O' locale modifier characters were accepted, +and the 'C' specification was a synonym for the 'c' specification. +.PP +The 'y' (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). +.SH "SEE ALSO" +.BR time (2), +.BR getdate (3), +.BR scanf (3), +.BR setlocale (3), +.BR strftime (3) |