strftime.3p (28556B)
- '\" 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 .