strftime Subroutine

Edit online

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;

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).
    %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 the %Y−%m−%d format (the ISO 8601 date format). [tm_year, tm_mon, tm_mday].
    %G Represents the ISO 8601 week-based year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year. (Calculated from tm_year, tm_yday, and tm_wday.)
    %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.
    %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 can not 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.
    %Y Represents the year as a decimal number (for example, 1989).
    %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:

Item Description
%Ec Represents the locale's alternative appropriate date and time as defined by the era_d_t_fmt statement.
%EC Represents the name of the base year (or other time period) in the locale's alternative form as defined by the era statement under the era_name category of the current era.
%Ex Represents the locale's alternative date as defined by the era_d_fmt statement.
%EX Represents the locale's alternative time as defined by the era_t_fmt statement.
%Ey Represents the offset from the %EC modified conversion specifier (year only) in the locale's alternative form.
%EY Represents the full alternative-year form.
%Od Represents the day of the month, using the locale's alternative numeric symbols, filled as needed with leading 0's if an alternative symbol for 0 exists. If an alternative symbol for 0 does not exist, the %Od modified conversion specifier uses leading space characters.
%Oe Represents the day of the month, using the locale's alternative numeric symbols, filled as needed with leading 0's if an alternative symbol for 0 exists. If an alternative symbol for 0 does not exist, the %Oe modified conversion specifier uses leading space characters.
%OH Represents the hour in 24-hour clock time, using the locale's alternative numeric symbols.
%OI Represents the hour in 12-hour clock time, using the locale's alternative numeric symbols.
%Om Represents the month, using the locale's alternative numeric symbols.
%OM Represents the minutes, using the locale's alternative numeric symbols.
%OS Represents the seconds, using the locale's alternative numeric symbols.
%Ou Represents the weekday as a number using the locale's alternative numeric symbols.
%OU Represents the week number of the year, using the locale's alternative numeric symbols. Sunday is considered the first day of the week. Use the rules corresponding to the %U conversion specifier.
%OV Represents the week number of the year (Monday as the first day of the week, rules corresponding to %V) using the locale's alternative numeric symbols.
%Ow Represents the number of the weekday (with Sunday equal to 0), using the locale's alternative numeric symbols.
%OW Represents the week number of the year using the locale's alternative numeric symbols. Monday is considered the first day of the week. Use the rules corresponding to the %W conversion specifier.
%Oy Represents the year (offset from %C) using the locale's alternative numeric symbols.

Parameters

Item Description
String Points to the string to hold the formatted time.
Length Specifies the maximum length of the string pointed to by the String parameter.
Format Points to the format character string.
TmDate Points to the time structure that is to be converted.

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.