diff options
Diffstat (limited to 'upstream/archlinux/man3p/strftime.3p')
| -rw-r--r-- | upstream/archlinux/man3p/strftime.3p | 1004 |
1 files changed, 1004 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/strftime.3p b/upstream/archlinux/man3p/strftime.3p new file mode 100644 index 00000000..1a1c4b23 --- /dev/null +++ b/upstream/archlinux/man3p/strftime.3p @@ -0,0 +1,1004 @@ +'\" et +.TH STRFTIME "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 +strftime, +strftime_l +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include <time.h> +.P +size_t strftime(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP); +size_t strftime_l(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrftime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrftime\fR() +function shall place bytes into the array pointed to by +.IR s +as controlled by the string pointed to by +.IR format . +The format is a character string, beginning and ending in its initial +shift state, if any. The format string consists of zero or more conversion +specifications and ordinary characters. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag: +.RS 4 +.IP "\fR0\fR" 6 +The zero character (\c +.BR '0' ), +which specifies that the character used as the padding character is +.BR '0' , +.IP "\fR+\fR" 6 +The +<plus-sign> +character (\c +.BR '+' ), +which specifies that the character used as the padding character is +.BR '0' , +and that if and only if the field being produced consumes more than four +bytes to represent a year (for +.BR %F , +.BR %G , +or +.BR %Y ) +or more than two bytes to represent the year divided by 100 (for +.BR %C ) +then a leading +<plus-sign> +character shall be included if the year being processed is greater than +or equal to zero or a leading +<hyphen-minus> +character (\c +.BR '\-' ) +shall be included if the year is less than zero. +.P +The default padding character is unspecified. +.RE +.IP " *" 4 +An optional minimum field width. If the converted value, including +any leading +.BR '+' +or +.BR '\-' +sign, has fewer bytes than the minimum field width and the padding +character is not the NUL character, the output shall be padded on the left +(after any leading +.BR '+' +or +.BR '\-' +sign) with the padding character. +.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 results are unspecified if more than one flag character is specified, +a flag character is specified without a minimum field width; a minimum +field width is specified without a flag character; a modifier is specified +with a flag or with a minimum field width; or if a minimum field width +is specified for any conversion specifier other than +.BR C , +.BR F , +.BR G , +or +.BR Y . +.P +All ordinary characters (including the terminating NUL character) +are copied unchanged into the array. If copying takes place between +objects that overlap, the behavior is undefined. No more than maxsize +bytes are placed into the array. Each conversion specifier is replaced by +appropriate characters as described in the following list. The appropriate +characters are determined using the +.IR LC_TIME +category of the current locale and by the values of zero or more members +of the broken-down time structure pointed to by +.IR timeptr , +as specified in brackets in the description. If any of the specified +values are outside the normal range, the characters stored are +unspecified. +.P +The +\fIstrftime_l\fR() +function shall be equivalent to the +\fIstrftime\fR() +function, except that the locale data used is from the +locale represented by +.IR locale . +.P +Local timezone information is used as though +\fIstrftime\fR() +called +\fItzset\fR(). +.P +The following conversion specifiers shall be supported: +.IP "\fRa\fR" 8 +Replaced by the locale's abbreviated weekday name. [\c +.IR tm_wday ] +.IP "\fRA\fR" 8 +Replaced by the locale's full weekday name. [\c +.IR tm_wday ] +.IP "\fRb\fR" 8 +Replaced by the locale's abbreviated month name. [\c +.IR tm_mon ] +.IP "\fRB\fR" 8 +Replaced by the locale's full month name. [\c +.IR tm_mon ] +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +(See the Base Definitions volume of POSIX.1\(hy2017, +.IR <time.h> .) +.IP "\fRC\fR" 8 +Replaced by the year divided by 100 and truncated to an integer, +as a decimal number. [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is not specified, the number of characters +placed into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or two, whichever +is greater. +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or the minimum +field width, whichever is greater. +.RE +.IP "\fRd\fR" 8 +Replaced by the day of the month as a decimal number [01,31]. [\c +.IR tm_mday ] +.IP "\fRD\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +[\c +.IR tm_mon , +.IR tm_mday , +.IR tm_year ] +.IP "\fRe\fR" 8 +Replaced by the day of the month as a decimal number [1,31]; +a single digit is preceded by a space. [\c +.IR tm_mday ] +.IP "\fRF\fR" 8 +Equivalent to %\*!+4\*?Y-%m-%d if no flag and no minimum field width +are specified. [\c +.IR tm_year , +.IR tm_mon , +.IR tm_mday ] +.RS 8 +.P +If a minimum field width of +.IR x +is specified, the year shall be output as if by the +.BR Y +specifier (described below) with whatever flag was given and a minimum +field width of +.IR x \-6. +If +.IR x +is less than 6, the behavior shall be as if +.IR x +equalled 6. +.P +If the minimum field width is specified to be 10, and the year is +four digits long, then the output string produced will match the +ISO\ 8601:\|2004 standard subclause 4.1.2.2 complete representation, extended format date +representation of a specific day. If a + flag is specified, a minimum +field width of +.IR x +is specified, and +.IR x \-7 +bytes are sufficient to hold the digits of the year (not including any +needed sign character), then the output will match the ISO\ 8601:\|2004 standard subclause +4.1.2.4 complete representation, expanded format date representation of +a specific day. +.RE +.IP "\fRg\fR" 8 +Replaced by the last 2 digits of the week-based year (see below) +as a decimal number [00,99]. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRG\fR" 8 +Replaced by the week-based year (see below) as a decimal number +(for example, 1977). [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +[\c +.IR tm_mon ] +.IP "\fRH\fR" 8 +Replaced by the hour (24-hour clock) as a decimal number [00,23]. [\c +.IR tm_hour ] +.IP "\fRI\fR" 8 +Replaced by the hour (12-hour clock) as a decimal number [01,12]. [\c +.IR tm_hour ] +.IP "\fRj\fR" 8 +Replaced by the day of the year as a decimal number [001,366]. [\c +.IR tm_yday ] +.IP "\fRm\fR" 8 +Replaced by the month as a decimal number [01,12]. [\c +.IR tm_mon ] +.IP "\fRM\fR" 8 +Replaced by the minute as a decimal number [00,59]. [\c +.IR tm_min ] +.IP "\fRn\fR" 8 +Replaced by a +<newline>. +.IP "\fRp\fR" 8 +Replaced by the locale's equivalent of either a.m. or p.m. [\c +.IR tm_hour ] +.IP "\fRr\fR" 8 +Replaced by the time in a.m. and p.m. notation; +in the POSIX locale this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRR\fR" 8 +Replaced by the time in 24-hour notation (\c +.BR %H :\c +.BR %M ). +[\c +.IR tm_hour , +.IR tm_min ] +.IP "\fRS\fR" 8 +Replaced by the second as a decimal number [00,60]. [\c +.IR tm_sec ] +.IP "\fRt\fR" 8 +Replaced by a +<tab>. +.IP "\fRT\fR" 8 +Replaced by the time (\c +.BR %H :\c +.BR %M :\c +.BR %S ). +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRu\fR" 8 +Replaced by the weekday as a decimal number [1,7], with 1 representing +Monday. [\c +.IR tm_wday ] +.IP "\fRU\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Sunday of January is the first day of week 1; days in the +new year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week) as a decimal number [01,53]. If the week 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. Both January 4th and the first Thursday of January are +always in week 1. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRw\fR" 8 +Replaced by the weekday as a decimal number [0,6], with 0 representing +Sunday. [\c +.IR tm_wday ] +.IP "\fRW\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Monday of January is the first day of week 1; days in the new +year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRx\fR" 8 +Replaced by the locale's appropriate date representation. (See +the Base Definitions volume of POSIX.1\(hy2017, +.IR <time.h> .) +.IP "\fRX\fR" 8 +Replaced by the locale's appropriate time representation. (See +the Base Definitions volume of POSIX.1\(hy2017, +.IR <time.h> .) +.IP "\fRy\fR" 8 +Replaced by the last two digits of the year as a decimal number +[00,99]. [\c +.IR tm_year ] +.IP "\fRY\fR" 8 +Replaced by the year as a decimal number (for example, 1997). [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRz\fR" 8 +Replaced by the offset from UTC in the ISO\ 8601:\|2004 standard format (\c +.BR +hhmm +or +.BR \-hhmm ), +or by no characters if no timezone is determinable. For example, +.BR \(dq-0430\(dq +means 4 hours 30 minutes behind UTC (west of Greenwich). +If +.IR tm_isdst +is zero, the standard time offset is used. If +.IR tm_isdst +is greater than zero, the daylight savings time offset is used. If +.IR tm_isdst +is negative, no characters are returned. +[\c +.IR tm_isdst ] +.IP "\fRZ\fR" 8 +Replaced by the timezone name or abbreviation, or by no bytes if no +timezone information exists. [\c +.IR tm_isdst ] +.IP "\fR%\fR" 8 +Replaced by +.BR % . +.P +If a conversion specification does not correspond to any of the above, +the behavior is undefined. +.P +If a +.BR "struct tm" +broken-down time structure is created by +\fIlocaltime\fR() +or +\fIlocaltime_r\fR(), +or modified by +\fImktime\fR(), +and the value of +.IR TZ +is subsequently modified, the results of the +.BR %Z +and +.BR %z +\fIstrftime\fR() +conversion specifiers are undefined, when +\fIstrftime\fR() +is called with such a broken-down time structure. +.P +If a +.BR "struct tm" +broken-down time structure is created or modified by +\fIgmtime\fR() +or +\fIgmtime_r\fR(), +it is unspecified whether the result of the +.BR %Z +and +.BR %z +conversion specifiers shall refer to UTC or the current local timezone, +when +\fIstrftime\fR() +is called with such a broken-down time structure. +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +or +.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 for the current locale (see ERA in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.5" ", " "LC_TIME"), +the behavior shall be as if the unmodified conversion +specification were used. +.IP "\fR%Ec\fR" 8 +Replaced by the locale's alternative appropriate date and time +representation. +.IP "\fR%EC\fR" 8 +Replaced by the name of the base year (period) in the locale's +alternative representation. +.IP "\fR%Ex\fR" 8 +Replaced by the locale's alternative date representation. +.IP "\fR%EX\fR" 8 +Replaced by the locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +Replaced by the offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +Replaced by the full alternative year representation. +.IP "\fR%Od\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading zeros if there is any +alternative symbol for zero; otherwise, with leading +<space> +characters. +.IP "\fR%Oe\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading +<space> +characters. +.IP "\fR%OH\fR" 8 +Replaced by the hour (24-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%OI\fR" 8 +Replaced by the hour (12-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%Om\fR" 8 +Replaced by the month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +Replaced by the minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +Replaced by the seconds using the locale's alternative numeric symbols. +.IP "\fR%Ou\fR" 8 +Replaced by the weekday as a number in the locale's alternative +representation (Monday=1). +.IP "\fR%OU\fR" 8 +Replaced by the week number of the year (Sunday as the first day of the +week, rules corresponding to +.BR %U ) +using the locale's alternative numeric symbols. +.IP "\fR%OV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week, rules corresponding to +.BR %V ) +using the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +Replaced by the number of the weekday (Sunday=0) using the locale's +alternative numeric symbols. +.IP "\fR%OW\fR" 8 +Replaced by 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 +Replaced by the year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +.BR %g , +.BR %G , +and +.BR %V +give values according to the ISO\ 8601:\|2004 standard week-based year. In this system, +weeks begin on a Monday and week 1 of the year is the week that +includes January 4th, which is also the week that includes the first +Thursday of the year, and is also the first week that contains at least +four days in the year. If the first Monday of January is the 2nd, 3rd, +or 4th, the preceding days are part of the last week of the preceding +year; thus, for Saturday 2nd January 1999, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and +any following days are part of week 1 of the following year. Thus, for +Tuesday 30th December 1997, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 01. +.P +If a conversion specifier is not one of the above, the behavior is +undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrftime_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If the total number of resulting bytes including the terminating null +byte is not more than +.IR maxsize , +these functions shall return the number of bytes placed into the array +pointed to by +.IR s , +not including the terminating NUL character. Otherwise, 0 shall be returned +and the contents of the array are unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting a Localized Date String" +.P +The following example first sets the locale to the user's default. The +locale information will be used in the +\fInl_langinfo\fR() +and +\fIstrftime\fR() +functions. The +\fInl_langinfo\fR() +function returns the localized date string which specifies how the date +is laid out. The +\fIstrftime\fR() +function takes this information and, using the +.BR tm +structure for values, places the date and time information into +.IR datestring . +.sp +.RS 4 +.nf + +#include <time.h> +#include <locale.h> +#include <langinfo.h> +\&... +struct tm *tm; +char datestring[256]; +\&... +setlocale (LC_ALL, ""); +\&... +strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The range of values for +.BR %S +is [00,60] rather than [00,59] to allow for the occasional leap +second. +.P +Some of the conversion specifications are duplicates of others. They +are included for compatibility with +\fInl_cxtime\fR() +and +\fInl_ascxtime\fR(), +which were published in Issue 2. +.P +The +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +format specifiers in +\fIstrftime\fR() +always print full values, but the +\fIstrptime\fR() +.BR %C , +.BR %F , +and +.BR %Y +format specifiers only scan two digits (assumed to be the first two +digits of a four-digit year) for +.BR %C +and four digits (assumed to be the entire (four-digit) year) for +.BR %F +and +.BR %Y . +This mimics the behavior of +\fIprintf\fR() +and +\fIscanf\fR(); +that is: +.sp +.RS 4 +.nf + +printf("%2d", x = 1000); +.fi +.P +.RE +.P +prints +.BR \(dq1000\(dq , +but: +.sp +.RS 4 +.nf + +scanf(%2d", &x); +.fi +.P +.RE +.P +when given +.BR \(dq1000\(dq +as input will only store 10 in +.IR x ). +Applications using extended ranges of years must be sure that the number +of digits specified for scanning years with +\fIstrptime\fR() +matches the number of digits that will actually be present in the input +stream. Historic implementations of the +.BR %Y +conversion specification (with no flags and no minimum field width) +produced different output formats. Some always produced at least four +digits (with 0 fill for years from 0 through 999) while others only +produced the number of digits present in the year (with no fill and no +padding). These two forms can be produced with the +.BR '0' +flag and a minimum field width options using the conversions +specifications +.BR %04Y +and +.BR %01Y , +respectively. +.P +In the past, the C and POSIX standards specified that +.BR %F +produced an ISO\ 8601:\|2004 standard date format, but didn't specify which one. For +years in the range [0001,9999], POSIX.1\(hy2008 requires that the output +produced match the ISO\ 8601:\|2004 standard complete representation extended format +(YYYY-MM-DD) and for years outside of this range produce output +that matches the ISO\ 8601:\|2004 standard expanded representation extended format +(<+/-><Underline>Y</Underline>YYYY-MM-DD). To fully meet ISO\ 8601:\|2004 standard +requirements, the producer and consumer must agree on a date format that +has a specific number of bytes reserved to hold the characters used to +represent the years that is sufficiently large to hold all values that +will be shared. For example, the +.BR %+13F +conversion specification will produce output matching the format +.BR \(dq<+/->YYYYYY-MM-DD\(dq +(a leading +.BR '+' +or +.BR '\-' +sign; a six-digit, 0-filled year; a +.BR '\-' ; +a two-digit, leading 0-filled month; another +.BR '\-' ; +and the two-digit, leading 0-filled day within the month). +.P +Note that if the year being printed is greater than 9999, the resulting +string from the unadorned +.BR %F +conversion specifications will not conform to the ISO\ 8601:\|2004 standard extended format, +complete representation for a date and will instead be an extended format, +expanded representation (presumably without the required agreement +between the date's producer and consumer). +.P +In the C or POSIX locale, the +.BR E +and +.BR O +modifiers are ignored and the replacement strings for the following +specifiers are: +.IP "\fR%a\fR" 8 +The first three characters of +.BR %A . +.IP "\fR%A\fR" 8 +One of Sunday, Monday, .\|.\|., Saturday. +.IP "\fR%b\fR" 8 +The first three characters of +.BR %B . +.IP "\fR%B\fR" 8 +One of January, February, .\|.\|., December. +.IP "\fR%c\fR" 8 +Equivalent to +.BR %a +.BR %b +.BR %e +.BR %T +.BR %Y . +.IP "\fR%p\fR" 8 +One of AM or PM. +.IP "\fR%r\fR" 8 +Equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%x\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fR%X\fR" 8 +Equivalent to +.BR %T . +.IP "\fR%Z\fR" 8 +Implementation-defined. +.SH RATIONALE +The +.BR %Y +conversion specification to +\fIstrftime\fR() +was frequently assumed to be a four-digit year, but the ISO\ C standard does not +specify that +.BR %Y +is restricted to any subset of allowed values from the +.IR tm_year +field. Similarly, the +.BR %C +conversion specification was assumed to be a two-digit field and the +first part of the output from the +.BR %F +conversion specification was assumed to be a four-digit field. With +.IR tm_year +being a signed 32 or more-bit +.BR int +and with many current implementations supporting 64-bit +.BR time_t +types in one or more programming environments, these assumptions are +clearly wrong. +.P +POSIX.1\(hy2008 now allows the format specifications +.BR %0xC , +.BR %0xF , +.BR %0xG , +and +.BR %0xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of a +string of +.IR x +decimal digits) with leading zero fill characters. Allowing applications +to set the field width enables them to agree on the number of digits +to be printed and scanned in the ISO\ 8601:\|2004 standard expanded representation of a +year (for +.BR %F , +.BR %G , +and +.BR %Y ) +or all but the last two digits of the year (for +.BR %C ). +This is based on a feature in some versions of GNU +.BR libc 's +\fIstrftime\fR(). +The GNU version allows specifying space, zero, or no-fill characters in +\fIstrftime\fR() +format strings, but does not allow any flags to be specified in +\fIstrptime\fR() +format strings. These implementations also allow these flags to be +specified for any numeric field. POSIX.1\(hy2008 only requires the zero fill flag +(\c +.BR '0' ) +and only requires that it be recognized when processing +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +specifications when a minimum field width is also specified. The +.BR '0' +flag is the only flag needed to produce and scan the ISO\ 8601:\|2004 standard +year fields using the extended format forms. POSIX.1\(hy2008 also allows +applications to specify the same flag and field width specifiers to be +used in both +\fIstrftime\fR() +and +\fIstrptime\fR() +format strings for symmetry. Systems may provide other flag characters +and may accept flags in conjunction with conversion specifiers other than +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y ; +but portable applications cannot depend on such extensions. +.P +POSIX.1\(hy2008 now also allows the format specifications +.BR %+xC , +.BR %+xF , +.BR %+xG , +and +.BR %+xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of +a string of +.BR 'x' +decimal digits) with leading zero fill characters and a leading +.BR '+' +sign character if the year being converted is more than four digits +or a minimum field width is specified that allows room for more than +four digits for the year. This allows date providers and consumers to +agree on a specific number of digits to represent a year as required by +the ISO\ 8601:\|2004 standard expanded representation formats. The expanded representation +formats all require the year to begin with a leading +.BR '+' +or +.BR '\-' +sign. +(All of these specifiers can also provide a leading +.BR '\-' +sign for negative years. Since negative years and the year 0 don't fit +well with the Gregorian or Julian calendars, the normal ranges of dates +start with year 1. The ISO\ C standard allows +.IR tm_year +to assume values corresponding to years before year 1, but the use of +such years provided unspecified results.) +.P +Some earlier version of this standard specified that applications wanting +to use +\fIstrptime\fR() +to scan dates and times printed by +\fIstrftime\fR() +should provide non-digit characters between fields to separate years +from months and days. It also supported +.BR %F +to print and scan the ISO\ 8601:\|2004 standard extended format, complete representation date +for years 1 through 9999 (i.e., YYYY-MM-DD). However, many applications +were written to print (using +\fIstrftime\fR()) +and scan (using +\fIstrptime\fR()) +dates written using the basic format complete representation +(four-digit years) and truncated representation (two-digit years) +specified by the ISO\ 8601:\|2004 standard representation of dates and times which do not +have any separation characters between fields. The ISO\ 8601:\|2004 standard also specifies +basic format expanded representation where the creator and consumer of +these fields agree beforehand to represent years as leading zero-filled +strings of an agreed length of more than four digits to represent a year +(again with no separation characters when year, month, and day are all +displayed). Applications producing and consuming expanded representations +are encouraged to use the +.BR '+' +flag and an appropriate maximum field width to scan the year including +the leading sign. Note that even without the +.BR '+' +flag, years less than zero may be represented with a leading +<hyphen-minus> +for +.BR %F , +.BR %G , +and +.BR %Y +conversion specifications. Using negative years results in unspecified +behavior. +.P +If a format specification +.BR %+xF +with the field width +.IR x +greater than 11 is specified and the width is large enough to display +the full year, the output string produced will match the ISO\ 8601:\|2004 standard +subclause 4.1.2.4 expanded representation, extended format date +representation for a specific day. (For years in the range [1,99\|999], +.BR %+12F +is sufficient for an agreed five-digit year with a leading sign using +the ISO\ 8601:\|2004 standard expanded representation, extended format for a specific day +.BR \(dq<+/->YYYYY-MM-DD\(dq .) +Note also that years less than 0 may produce a leading +<hyphen-minus> +character (\c +.BR '\-' ) +when using +.BR %Y +or +.BR %C +whether or not the +.BR '0' +or +.BR '+' +flags are used. +.P +The difference between the +.BR '0' +flag and the +.BR '+' +flag is whether the leading +.BR '+' +character will be provided for years >9999 as required for the ISO\ 8601:\|2004 standard +extended representation format containing a year. For example: +.TS +box center tab(!); +cB | cB | cB | cB +cB | cB | cB | cB +l | lf5 | l | l. +!!\fIstrftime\fP(\^)!\fIstrptime\fP(\^) +Year!Conversion Specification!Output!Scan Back +_ +1970!%Y!1970!1970 +_ +1970!%+4Y!1970!1970 +_ +27!%Y!27 or 0027!27 +_ +270!%Y!270 or 0270!270 +_ +270!%+4Y!0270!270 +_ +17!%C%y!0017!17 +_ +270!%C%y!0270!270 +_ +12345!%Y!12345!1234* +_ +12345!%+4Y!+12345!123* +_ +12345!%05Y!12345!12345 +_ +270!%+5Y \fRor\fP %+3C%y!+0270!270 +_ +12345!%+5Y \fRor\fP %+3C%y!+12345!1234* +_ +12345!%06Y \fRor\fP %04C%y!012345!12345 +_ +12345!%+6Y \fRor\fP %+4C%y!+12345!12345 +_ +123456!%08Y \fRor\fP %06C%y!00123456!123456 +_ +123456!%+8Y \fRor\fP %+6C%y!+0123456!123456 +.TE +.P +In the cases above marked with a * in the +\fIstrptime\fR() +scan back field, the implied or specified number of characters scanned by +\fIstrptime\fR() +was less than the number of characters output by +\fIstrftime\fR() +using the same format; so the remaining digits of the year were dropped +when the output date produced by +\fIstrftime\fR() +was scanned back in by +\fIstrptime\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.5" ", " "LC_TIME", +.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 . |