strftime 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;

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

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.