strftime, strftime_l, cftime, ascftime - convert date and time to string
#include <time.h>
size_t strftime(char *restrict s, size_t maxsize,
const char *restrict format,
const struct tm *restrict timeptr);
size_t strftime_l(char *restrict s, size_t maxsize,
const char *restrict format,
const struct tm *restrict timeptr,
locale_t locale);
int cftime(char *s, char *format, const time_t *clock);
int ascftime(char *s, const char *format,
const struct tm *timeptr);
The strftime(), ascftime(), and cftime() functions place bytes into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more conversion specifications and ordinary characters. A conversion specification consists of a '%' (percent) character, an optional flag character, an optional field width, and one or two terminating conversion characters that determine the conversion specification's behavior. All ordinary characters (including the terminating null byte) are copied unchanged into the array pointed to by s. If copying takes place between objects that overlap, the behavior is undefined. For strftime(), no more than maxsize bytes are placed into the array.
If format is (char *)0, then the locale's default format is used. For strftime() the default format is the same as %c; for cftime() and ascftime() the default format is the same as %C. cftime() and ascftime() first try to use the value of the environment variable CFTIME, and if that is undefined or empty, the default format is used.
Each conversion specification is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the LC_TIME category of current locale or of locale specified by locale, and by the values contained in the structure pointed to by timeptr for strftime(), strftime_l(), and ascftime(), and by the time represented by clock for cftime(). Supported optional flag characters and optional field width are described at the end of the section.
Each conversion specification is introduced by the '%' character after which the following appear in sequence:
Specifies that the character used as the padding character is '0', even in cases where the conversion specification character used with is specified with in the "Conversion Specifiers" subsection such that digits are preceded by a space or a blank character.
This character is not recognized as an optional flag. Instead, this character is recognized as a conversion specifier. See "Conversion Specifiers" section.
Specifies that the character used as the padding character is '0', and that if and only if the field being produced consumes more than four bytes to represent a year (for %F, %G, or %Y) or more than two bytes to represent the year divided by 100 (for %C) then a leading plus-sign character is included if the year being processed is greater than or equal to zero or a leading minus-sign character ('-') is included if the year is less than zero.
If applicable, convert the case of the alphabetic characters to the other case, i.e., uppercase to lowercase or lowercase to uppercase, while trying to preserve the first so-called title case character in the conversion to uppercase.
Do not pad anything for numeric values.
If applicable, convert lowercase characters into uppercase characters.
Pad left with space (0x20) characters for numeric values.
If the converted value has fewer bytes than the minimum field width, the output will be padded on the left with the padding character.
In SUSv4 conforming application, a leading '+' or '-' sign is included when counting bytes for the converted values, and a padding is done after any leading '+' or '-' sign.
Subsection "Modified Conversion Specifications" describes about how those modifiers work.
The specifier indicates the type of conversion to be applied. Subsection "Conversion Specifiers" describes about the specifiers supported.
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 C, F, G, or Y.
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 LC_TIME category of the current locale or locale specified by locale and by the values of zero or more members of the broken-down time structure pointed to by timeptr, as specified in brackets in the description. If any of the specified values are outside the normal range, the characters stored are unspecified.
The following conversion specifiers are supported:
Locale's date and time representation as produced by date(1). Plus sign is recognized as a conversion specifier.
This character is not recognized as a conversion specifier. Instead, this character is recognized as an optional flag. See "Description" section.
Locale's abbreviated weekday name.
Locale's full weekday name.
Locale's abbreviated month name.
Locale's full month name.
Locale's appropriate date and time represented as:
%a %b %e %H:%M:%S %Y
This is standard-conforming behavior for standards first supported by Solaris 2.4 through Oracle Solaris 11.4.
Locale's appropriate date and time represented as:
%a %b %d %H:%M:%S %Y
This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Solaris 2.4. See standards(7).
Century number (the year divided by 100 and truncated to an integer as a decimal number [01,99]).
If a minimum field width is not specified, the number of characters placed into the array pointed to by 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 s will be the number of digits in the year divided by 100 or the minimum field width, whichever is greater.
Century number (the year divided by 100 and truncated to an integer as a decimal number [01,99]).
This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Oracle Solaris 11.
Locale's date and time representation as produced by date(1).
This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Oracle Solaris 11.4.
Day of month as a decimal number [01,31].
Equivalent to %m/%d/%y.
Day of month as a decimal number [1,31]; a single digit is preceded by a space.
Equivalent to %+4Y-%m-%d if no flag and no minimum field width are specified.
If a minimum field width of x is specified, the year is output as if by the Y specifier (described below) with whatever flag was given and a minimum field width of x-6. If x is less than 6, the behavior is as if x equals 6.
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:2000 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 x is specified, and 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:2000 standard subclause 4.1.2.4 complete representation, expanded format date representation of a specific day.
Equivalent to %Y-%m-%d (the ISO 8601:2000 standard + date in extended format).
This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Oracle Solaris 11.4.
Last 2 digits of the week-based year as a decimal number [00,99].
Week-based year as a decimal number (for example, 1977).
If a minimum field width is specified, the number of characters placed into the array pointed to by s will be the number of digits and leading sign characters (if any) in the year, or the minimum field width, whichever is greater.
Week-based year, including the century [0000,9999].
This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Oracle Solaris 11.4.
Equivalent to b.
Hour (24-hour clock) as a decimal number [00,23].
Hour (12-hour clock) as a decimal number [01,12].
Day number of year as a decimal number [001,366].
Hour (24-hour clock) as a decimal number [0,23]; single digit is preceded by a space.
Hour (12-hour clock) as a decimal number [1,12]; single digit is preceded by a space.
Month as a decimal number [01,12].
Minute as a decimal number [00,59].
A NEWLINE.
Locale's equivalent of either a.m. or p.m.
Appropriate time representation in 12-hour clock format with %p. In the POSIX locale this is equivalent to %I:%M:%S %p.
Locale's equivalent of either a.m. or p.m. in lowercase if applicable for the current locale, or in locale represented by locale in strftime_l().
Time in 24-hour notation as %H:%M.
The number of seconds since the Epoch (00:00:00 UTC, January 1, 1970).
Second as a decimal number [00,60]; the range of values is [00,60] rather than [00,59] to allow for the occasional leap second.
A TAB.
Time as %H:%M:%S.
Weekday as a decimal number [1,7], with 1 representing Monday. See NOTES below.
Week number of 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.
The ISO 8601 week number as a decimal number [01,53]. In the ISO 8601 week-based system, weeks begin on a Monday and week 1 of the year is the week that includes both January 4th and the first Thursday of 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. See NOTES below.
Weekday as a decimal number [0,6], with 0 representing Sunday.
Week number of year as a decimal number [00,53], with Monday as the first day of week 1. The first Monday of January is the first day of week 1; days in the new year before this are in week 0.
Locale's appropriate date representation.
Locale's appropriate time representation.
Year as a decimal number (for example 1997).
If a minimum field width is specified, the number of characters placed into the array pointed to by s will be the number of digits and leading sign characters (if any) in the year, or the minimum field width, whichever is greater.
Year as a decimal number (for example 1997). This is the default behavior as well as standard-conforming behavior for standards first supported by releases prior to Oracle Solaris 11.4.
Replaced by offset from UTC in ISO 8601:2004 standard basic format (+hhmm or -hhmm), or by no characters if no time zone is determinable. For example, "-0430" means 4 hours 30 minutes behind UTC (west of Greenwich). If tm_isdst is negative no characters are returned.
Time zone name or abbreviation, or no bytes if no time zone information exists.
Replaced by %.
If a conversion specification does not correspond to any of the above or to any of the modified conversion specifications listed below, the behavior is undefined and 0 is returned.
The difference between %U and %W (and also between modified conversion specifications %OU and %OW) lies in which day is counted as the first of the week. Week number 1 is the first week in January starting with a Sunday for %U or a Monday for %W. Week number 0 contains those days before the first Sunday or Monday in January for %U and %W, respectively.
Some conversion specifications can be modified by the E and O modifiers to indicate that an alternate format or specification should be used rather than the one normally used by the unmodified conversion specification. If the alternate format or specification does not exist in the current locale, the behavior will be as if the unmodified specification were used.
Locale's alternate appropriate date and time representation.
Name of the base year (period) in the locale's alternate representation.
Offset from %EC of the week-based year in the locale's alternative representation.
Full alternative representation of the week-based year.
Locale's alternate date representation.
Locale's alternate time representation.
Offset from %EC (year only) in the locale's alternate representation.
Full alternate year representation.
Locale's full month name using the locale's alternate numeric symbols if applicable.
Day of the month using the locale's alternate numeric symbols.
Same as %Od.
Week-based year (offset from %C) in the locale's alternate representation and using the locale's alternate numeric symbols.
Hour (24-hour clock) using the locale's alternate numeric symbols.
Hour (12-hour clock) using the locale's alternate numeric symbols.
Month using the locale's alternate numeric symbols.
Minutes using the locale's alternate numeric symbols.
Seconds using the locale's alternate numeric symbols.
Weekday as a number in the locale's alternate numeric symbols.
Week number of the year (Sunday as the first day of the week) using the locale's alternate numeric symbols.
Week number of the year (Monday as the first day of the week as specified in the description for %V) using the locale's alternate numeric symbols.
Number of the weekday (Sunday=0) using the locale's alternate numeric symbols.
Week number of the year (Monday as the first day of the week) using the locale's alternate numeric symbols.
Year (offset from %C) in the locale's alternate representation and using the locale's alternate numeric symbols.
By default, the output of strftime(), cftime(), and ascftime() appear in U.S. English. The user can request that the output of strftime(), cftime(), or ascftime() be in a specific language by setting the LC_TIME category using setlocale().
The strftime_l() function is equivalent to the strftime() function, except that the locale data used is from the locale represented by locale.
The behavior is undefined if the locale argument to strftime_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.
Local time zone information is used as though tzset(3C) were called.
These functions return the number of bytes placed into the array pointed to by s, not including the terminating null character. If the total number of resulting bytes including the terminating null character is more than maxsize, strftime() and strftime_l() return 0 and the contents of the array are indeterminate.
The following example illustrates the use of strftime() to format a date and time in the ISO 8601:2019 extended format. It shows what the string in str would look like if the structure pointed to by tmptr contains the values corresponding to Thursday, August 28, 1986 at 12:44:36.
strftime(str, strsize, "%FT%T", tmptr)
This results in str containing “1986-08-28T12:44:36”.
Example 2 Locale appropriate date and timeGenerate the long form date and time represented by the variable now in the current locale appropriate order. Note that even in two different English locales this results in a string of different lengths and field order:
strftime(str, strsize, "%c", now)
Assuming the data structure pointed to by tmptr has the values corresponding to Sunday, December 5, 2009 at 12:00:00 and the current locale is POSIX, with the following:
strftime(str, strsize, "Day:%#10A", tmptr);
The result in str would be “Day: SUNDAY” where Sunday is converted to uppercase while preserving the initial title case character and with four space (0x20) characters padded at left.
See attributes(7) for descriptions of the following attributes:
|
For strftime() and strftime_l(), see standards(7).
date(1), ctime(3C), duplocale(3C), freelocale(3C), mktime(3C), newlocale(3C), setlocale(3C), strptime(3C), tzset(3C), uselocale(3C), zoneinfo(5), attributes(7), environ(7), standards(7)
The conversion specification for %V was changed in the Solaris 7 release. This change was based on the public review draft of the ISO C9x standard at that time. Previously, the specification stated that if the week containing 1 January had fewer than four days in the new year, it became week 53 of the previous year. The ISO C9x standard committee subsequently recognized that that specification had been incorrect.
The conversion specifications for %g, %G, %Eg, %EG, and %Og were added in the Solaris 7 release. This change was based on the public review draft of the ISO C9x standard at that time. These specifications are evolving. If the ISO C9x standard is finalized with a different conclusion, these specifications will change to conform to the ISO C9x standard decision.
The conversion specification for %u was changed in the Solaris 8 release. This change was based on the XPG4 specification.
If using the %Z specifier and zoneinfo time zones and if the input date is outside the range 20:45:52 UTC, December 13, 1901 to 03:14:07 UTC, January 19, 2038, the time zone name may not be correct.
The conversion specifications for %+, %P, %s, %OB, and %OV and also optional flag characters and optional field width were added in the Solaris 11 and OpenSolaris releases for a better compatibility with other operating systems. The current form of %OV is also specified in the Single UNIX Specification, Version 2.
The conversion specifications for %C, %F, %G, and %Y are modified, and optional flag character '+' is added in Oracle Solaris 11.4, to conform to Single UNIX Specifications version 4 (SUSv4) or The Open Group Base Specifications Issue 7 (XPG7).