strftime or strftime_l Subroutine

Purpose

Formats time and date.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>
size_t strftime ( String, Length, Format, TmDate)
char *String;
size_t Length;
const char *Format;
const struct tm *TmDate;

size_t strftime_l(char *restrict String, size_t Length,
const char *restrict Format, const struct tm *restrict TmDate,locale_t Locale);

Description

The strftime subroutine converts the internal time and date specification of the tm structure, which is pointed to by the TmDate parameter, into a character string pointed to by the String parameter under the direction of the format string pointed to by the Format parameter. The actual values for the format specifiers are dependent on the current settings for the LC_TIME category. The tm structure values may be assigned by the user or generated by the localtime or gmtime subroutine. The resulting string is similar to the result of the printf Format parameter, and is placed in the memory location addressed by the String parameter. The maximum length of the string is determined by the Length parameter and terminates with a null character.

Many conversion specifications are the same as those used by the date command. The interpretation of some conversion specifications is dependent on the current locale of the process.

The Format parameter is a character string containing two types of objects: plain characters that are simply placed in the output string, and conversion specifications that convert information from the TmDate parameter into readable form in the output string. Each conversion specification is a sequence of this form: % type.

• A % (percent sign) introduces a conversion specification.
• The type of conversion is specified by one or two conversion characters. The characters and their meanings are:

  Item	Description
  %a	Represents the locale's abbreviated weekday name (for example, Sun) defined by the abday statement in the LC_TIME category.
  %A	Represents the locale's full weekday name (for example, Sunday) defined by the day statement in the LC_TIME category.
  %b	Represents the locale's abbreviated month name (for example, Jan) defined by the abmon statement in the LC_TIME category.
  %B	Represents the locale's full month name (for example, January) defined by the mon statement in the LC_TIME category.
  %c	Represents the locale's date and time format defined by the d_t_fmt statement in the LC_TIME category.
  %C	Represents the century number (the year divided by 100 and truncated to an integer) as a decimal number (00 through 99 calculated from the standard term tm_year that is defined in the tm structure of the time.h library) If a minimum field width is not specified, the number of characters that are placed into the array pointed by the string parameter is 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 that are placed into the array pointed by the string parameter is the number of digits in the year divided by 100 or the minimum field width, whichever is greater.
  %d	Represents the day of the month as a decimal number (01 to 31).
  %D	Represents the date in %m/%d/%y format (for example, 01/31/91).
  %e	Represents the day of the month as a decimal number (01 to 31). The %e field descriptor uses a two-digit field. If the day of the month is not a two-digit number, the leading digit is filled with a space character.
  %E	Represents the locale's combined alternate era year and name, respectively, in %o %N format.
  %F	Represents the date in %+4Y-%m-%d format if no flag and no minimum field width are specified (calculated from the standard terms tm_year, tm_mon, and tm_mday that are defined in the tm structure of the time.h library). If a minimum field width of less than or equal to 6 bytes is specified, the output string of the year is same as the output string by the Y specifier with any specified flag and a minimum field width of 6 bytes. If the specified field width is less than 6 bytes, the field width is considered as 6 bytes by default. If the minimum field width is specified as 10 bytes, and the year is four digits long, the output string that is produced matches the ISO 8601:2000 standard subclause 4.1.2.2 complete representation, extended format date representation of a specific day (YYYY-MM-DD). For example, 2021-05-20. If a + flag and a minimum field width of greater than 6 bytes is specified, and 7 bytes are sufficient to hold the digits of the year (not including any sign character), the output string matches the ISO 8601:2000 standard subclause 4.1.2.4 complete representation, extended format date representation of a specific day (±YYYYY-MM-DD). For example, +002021-05-20.
  %G	Represents the week-based year as a decimal number, for example, 1977 (calculated from the standard terms tm_year, tm_wday, tm_yday that are defined in the tm structure of the time.h library). If a minimum field width is specified, the number of characters that are placed into the array pointed by the string parameter is the number of digits and leading sign characters (if any) in the year, or the minimum field width, whichever is greater.
  %g	Represents the last two digit of ISO 8601 week-based year as a decimal number (0 to 99). It's like %G, but without century. (Calculated from tm_year, tm_yday, and tm_wday.)
  %h	Represents the locale's abbreviated month name (for example, Jan) defined by the abmon statement in the LC_TIME category. This field descriptor is a synonym for the %b field descriptor.
  %H	Represents the 24-hour-clock hour as a decimal number (00 to 23).
  %I	Represents the 12-hour-clock hour as a decimal number (01 to 12).
  %j	Represents the day of the year as a decimal number (001 to 366).
  %k	Represents the 24-hour-clock hour clock as a right-justified space-filled number (0 to 23).
  %m	Represents the month of the year as a decimal number (01 to 12).
  %M	Represents the minutes of the hour as a decimal number (00 to 59).
  %n	Specifies a new-line character.
  %N	Represents the locale's alternate era name.
  %o	Represents the alternate era year.
  %p	Represents the locale's a.m. or p.m. string defined by the am_pm statement in the LC_TIME category.
  %r	Represents 12-hour clock time with a.m./p.m. notation as defined by the t_fmt_ampm statement. The usual format is %I:%M:%S %p.
  %R	Represents 24-hour clock time in %H:%M format.
  %s	Represents the number of seconds since January 1, 1970, Coordinated Universal Time (CUT).
  %S	Represents the seconds of the minute as a decimal number (00 to 59).
  %t	Specifies a tab character.
  %T	Represents 24-hour-clock time in the format %H:%M:%S (for example, 16:55:15).
  %u	Represents the weekday as a decimal number (1 to 7). Monday or its equivalent is considered the first day of the week for calculating the value of this field descriptor.
  %U	Represents the week of the year as a decimal number (00 to 53). Sunday, or its equivalent as defined by the day statement in the LC_TIME category, is considered the first day of the week for calculating the value of this field descriptor.
  %V	Represents the week number of the ISO 8601 week-based year (with Monday as the first day of the week) as a decimal number (01 to 53). If the week containing January 1 has four or more days in the new year, then it is considered week 1; otherwise, it is considered week 52 (or 53 if the previous year was a leap year) of the previous year, and the next week is week 1 of the new year.
  %w	Represents the day of the week as a decimal number (0 to 6). Sunday, or its equivalent as defined by the day statement, is considered as 0 for calculating the value of this field descriptor.
  %W	Represents the week of the year as a decimal number (00 to 53). Monday, or its equivalent as defined by the day statement, is considered the first day of the week for calculating the value of this field descriptor.
  %x	Represents the locale's date format as defined by the d_fmt statement.
  %X	Represents the locale's time format as defined by the t_fmt statement.
  %y	Represents the year of the century. Note: When the environment variable XPG_TIME_FMT=ON, %y is the year within the century. When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999, inclusive); values in the range 00-68 refer to 2000 to 2068, inclusive.
  %Y	Represents the year as a decimal number, for example, 1989 (calculated from the standard term tm_yearthat is defined in the tm structure of the time.h library). If a minimum field width is specified, the number of characters that are placed into the array pointed by the string parameter is the number of digits and leading sign characters (if any) in the year, or the minimum field width, whichever is greater.
  %z	Represents the offset from Coordinated Universal Time (UTC) in the ISO 8601 format −0430 means 4 hours 30 minutes behind UTC, west of Greenwich, or by no characters if you cannot determine the time zone [tm_isdst]. Note: You must set the value of the XPG_SUS_ENV=ON environment variable to use the %z option else it falls back to the %Z option.
  %Z	Represents the time-zone name if one can be determined (for example, EST). No characters are displayed if a time zone cannot be determined.
  %%	Specifies a % (percent sign).

Some conversion specifiers can be modified by the E or O modifier characters to indicate that an alternative format or specification should be used. If the alternative format or specification does not exist for the current locale, the behavior will be the same as with the unmodified conversion specification. The following modified conversion specifiers are supported:

The strftime_l() subroutine is similar to the strftime() subroutine, except the locale information that is specified in the locale variable. If the locale variable in the strftime_l() subroutine is set as a special locale object, LC_GLOBAL_LOCALE, or is not a valid locale object handle, the strftime_l() subroutine might result unexpected results.

Parameters

Return Values

If the total number of resulting bytes, including the terminating null byte, is not more than the Length value, the strftime subroutine returns the number of bytes placed into the array pointed to by the String parameter, not including the terminating null byte. Otherwise, a value of 0 is returned and the contents of the array are indeterminate.