diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/strptime.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/strptime.3p | 443 |
1 files changed, 443 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/strptime.3p b/man-pages-posix-2017/man3p/strptime.3p new file mode 100644 index 0000000..9c97491 --- /dev/null +++ b/man-pages-posix-2017/man3p/strptime.3p @@ -0,0 +1,443 @@ +'\" et +.TH STRPTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strptime +\(em date and time conversion +.SH SYNOPSIS +.LP +.nf +#include <time.h> +.P +char *strptime(const char *restrict \fIbuf\fP, const char *restrict \fIformat\fP, + struct tm *restrict \fItm\fP); +.fi +.SH DESCRIPTION +The +\fIstrptime\fR() +function shall convert the character string pointed to by +.IR buf +to values which are stored in the +.BR tm +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.P +The format 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\fR()); +an ordinary character (neither +.BR '%' +nor a white-space character); or a conversion specification. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag, the zero character (\c +.BR '0' ) +or the +<plus-sign> +character (\c +.BR '+' ), +which is ignored. +.IP " *" 4 +An optional field width. If a field width is specified, it shall be +interpreted as a string of decimal digits that will determine the maximum +number of bytes converted for the conversion rather than the number of +bytes specified below in the description of the conversion specifiers. +.IP " *" 4 +An optional +.BR E +or +.BR O +modifier. +.IP " *" 4 +A terminating conversion specifier character that indicates the type of +conversion to be applied. +.P +The conversions are determined using the +.IR LC_TIME +category of the current locale. The application shall ensure that +there is white-space or other non-alphanumeric characters between any +two conversion specifications unless all of the adjacent conversion +specifications convert a known, fixed number of characters. In the +following list, the maximum number of characters scanned (excluding the +one matching the next directive) is as follows: +.IP " *" 4 +If a maximum field width is specified, then that number +.IP " *" 4 +Otherwise, the pattern +.BR \(dq{x}\(dq +indicates that the maximum is +.IR x +.IP " *" 4 +Otherwise, the pattern +.BR \(dq[x,y]\(dq +indicates that the value shall fall within the range given (both bounds +being inclusive), and the maximum number of characters scanned shall be +the maximum required to represent any value in the range without leading +zeros and without a leading +<plus-sign> +.P +The following conversion specifiers are supported. +.P +The results are unspecified if a modifier is specified with a flag or +with a minimum field width, or if a field width is specified for any +conversion specifier other than +.BR C +or +.BR Y . +.IP "\fRa\fR" 8 +The day of the week, using the locale's weekday names; either the +abbreviated or full name may be specified. +.IP "\fRA\fR" 8 +Equivalent to +.BR %a . +.IP "\fRb\fR" 8 +The month, using the locale's month names; either the abbreviated or +full name may be specified. +.IP "\fRB\fR" 8 +Equivalent to +.BR %b . +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +.IP "\fRC\fR" 8 +All but the last two digits of the year {2}; leading zeros shall be +permitted but shall not be required. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fRd\fR" 8 +The day of the month [01,31]; leading zeros shall be permitted but shall +not be required. +.IP "\fRD\fR" 8 +The date as +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fRe\fR" 8 +Equivalent to +.BR %d . +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +.IP "\fRH\fR" 8 +The hour (24-hour clock) [00,23]; leading zeros shall be permitted but +shall not be required. +.IP "\fRI\fR" 8 +The hour (12-hour clock) [01,12]; leading zeros shall be permitted but +shall not be required. +.IP "\fRj\fR" 8 +The day number of the year [001,366]; leading zeros shall be permitted +but shall not be required. +.IP "\fRm\fR" 8 +The month number [01,12]; leading zeros shall be permitted but shall +not be required. +.IP "\fRM\fR" 8 +The minute [00,59]; leading zeros shall be permitted but shall not +be required. +.IP "\fRn\fR" 8 +Any white space. +.IP "\fRp\fR" 8 +The locale's equivalent of a.m. or p.m. +.IP "\fRr\fR" 8 +12-hour clock time using the AM/PM notation if +.BR t_fmt_ampm +is not an empty string in the +.IR LC_TIME +portion of the current locale; in the POSIX locale, this shall +be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fRR\fR" 8 +The time as +.BR %H :\c +.BR %M . +.IP "\fRS\fR" 8 +The seconds [00,60]; leading zeros shall be permitted but shall +not be required. +.IP "\fRt\fR" 8 +Any white space. +.IP "\fRT\fR" 8 +The time as +.BR %H :\c +.BR %M :\c +.BR %S . +.IP "\fRU\fR" 8 +The week number of the year (Sunday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRw\fR" 8 +The weekday as a decimal number [0,6], with 0 representing Sunday. +.IP "\fRW\fR" 8 +The week number of the year (Monday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRx\fR" 8 +The date, using the locale's date format. +.IP "\fRX\fR" 8 +The time, using the locale's time format. +.IP "\fRy\fR" 8 +The last two digits of the year. When +.IR format +contains neither a +.BR C +conversion specifier nor a +.BR Y +conversion specifier, 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. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.RS 8 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.IP "\fRY\fR" 8 +The full year {4}; leading zeros shall be permitted but shall +not be required. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fR%\fP" 8 +Replaced by +.BR % . +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +and +.BR O +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. +.IP "\fR%Ec\fR" 8 +The locale's alternative appropriate date and time representation. +.IP "\fR%EC\fR" 8 +The name of the base year (period) in the locale's alternative +representation. +.IP "\fR%Ex\fR" 8 +The locale's alternative date representation. +.IP "\fR%EX\fR" 8 +The locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +The offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +The full alternative year representation. +.IP "\fR%Od\fR" 8 +The day of the month using the locale's alternative numeric symbols; +leading zeros shall be permitted but shall not be required. +.IP "\fR%Oe\fR" 8 +Equivalent to +.BR %Od . +.IP "\fR%OH\fR" 8 +The hour (24-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%OI\fR" 8 +The hour (12-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%Om\fR" 8 +The month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +The minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +The seconds using the locale's alternative numeric symbols. +.IP "\fR%OU\fR" 8 +The week number of the year (Sunday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +The number of the weekday (Sunday=0) using the locale's alternative +numeric symbols. +.IP "\fR%OW\fR" 8 +The week number of the year (Monday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +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. +.P +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. +.P +A series of conversion specifications composed of +.BR %n , +.BR %t , +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. +.P +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 +.BR tm +structure members are set to values corresponding to the locale +information. Case is ignored when matching items in +.IR buf +such as month or weekday names. If no match is found, +\fIstrptime\fR() +fails and no more characters are scanned. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrptime\fR() +shall return a pointer to the character following the last character +parsed. Otherwise, a null pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds" +.P +The following example demonstrates the use of +\fIstrptime\fR() +to convert a string into broken-down time. The broken-down time is then +converted into seconds since the Epoch using +\fImktime\fR(). +.sp +.RS 4 +.nf + +#include <time.h> +\&... +.P +struct tm tm; +time_t t; +.P +if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL) + /* Handle error */; +.P +printf("year: %d; month: %d; day: %d;\en", + tm.tm_year, tm.tm_mon, tm.tm_mday); +printf("hour: %d; minute: %d; second: %d\en", + tm.tm_hour, tm.tm_min, tm.tm_sec); +printf("week day: %d; year day: %d\en", tm.tm_wday, tm.tm_yday); +.P +tm.tm_isdst = -1; /* Not set by strptime(); tells mktime() + to determine whether daylight saving time + is in effect */ +t = mktime(&tm); +if (t == -1) + /* Handle error */; +printf("seconds since the Epoch: %ld\en", (long) t);" +.fi +.P +.RE +.SH "APPLICATION USAGE" +Several ``equivalent to'' formats and the special processing of +white-space characters are provided in order to ease the use of +identical +.IR format +strings for +\fIstrftime\fR() +and +\fIstrptime\fR(). +.P +It should be noted that dates constructed by the +\fIstrftime\fR() +function with the +.BR %Y +or +.BR %C%y +conversion specifiers may have values larger than 9\|999. If the +\fIstrptime\fR() +function is used to read such values using +.BR %C%y +or +.BR %Y , +the year values will be truncated to four digits. Applications should use +.BR %+ \c +.IR w \c +.BR %y +or +.BR %+ \c +.IR x \c +.BR Y +with +.IR w +and +.IR x +set large enough to contain the full value of any years that will be +printed or scanned. +.P +See also the APPLICATION USAGE section in +.IR "\fIstrftime\fR\^(\|)". +.P +It is unspecified whether multiple calls to +\fIstrptime\fR() +using the same +.BR tm +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\fR() +with a format and all data needed to completely specify the date and +time being converted. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIstrftime\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<time.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |