NAME
strftime - Converts date and time to string
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <time.h>
size_t strftime(
char *s,
size_t maxsize,
const char *format,
const struct tm *timeptr) ;
PARAMETERS
s Points to the array containing the output date and
time string.
maxsize Specifies the maximum number of bytes to be writ-
ten to the array pointed to by the s parameter.
format Points to a sequence of control characters (refer
to the foregoing list) that specify the format of
the date and time string pointed to by the s
parameter.
timeptr Points to a type tm structure that contains
broken-down time information.
DESCRIPTION
The strftime() function places characters into the array
pointed to by the s parameter as controlled by the string
pointed to by the format parameter. The string pointed to by
the format parameter is a multibyte character sequence,
beginning and ending in its initial shift state.
Local time zone information is used as though the strftime()
function called the tzset() function. Time information used
in this subroutine is fetched from space containing type tm
structure data, which is defined in the time.h include file.
The type tm structure must contain the time information used
by this subroutine to construct the time and date string.
The format string consists of zero or more conversion
specifications and ordinary multibyte characters. A conver-
sion specification consists of a % (percent) character fol-
lowed by a character that determines how the conversion
specification constructs the formatted string.
All ordinary multibyte characters (including the terminating
null character) are copied unchanged into the s array. When
copying between objects that overlap takes place, behavior
of this function is undefined. No more than the number of
characters specified by the maxsize parameter are written to
the array. 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 the current locale and by values specified by
the type tm structure pointed to by the timeptr parameter.
This function uses the local timezone information.
The format parameter consists of a series of 0 or more
conversion specifiers and ordinary characters. Each conver-
sion specification starts with a percent sign (%) and ends
with a conversion code character specifying the conversion
format. The function replaces the conversion specification
with the appropriately formatted date or time value. Ordi-
nary characters are written to the output buffer unchanged.
The format parameter has the following syntax:
[ordinary-text] [% [ [-|0] width ] [ .precision ] format-
code [ordinary-text]]...
ordinary-text
Text that is copied to the output parameter with
no changes.
width A decimal digit string that specifies the
minimun field width. If the width of the item
equals or exceeds the minimum field width, the
minimum is ignored. If the width of the item is
less than the minimum field width, the function
justifies and pads the item. The optional minus
sign (-) or zero digit (0) control the justifi-
cation and padding as follows:
none Item is right justified and spaces are
added to the beginning of the item to
fill the minimum width.
minus signItem is left justified and spaces are
added to the end of the item to fill
the minimum width.
zero digitItem is right justified and zeros are
added to the beginning of the item to
fill the minimum width.
precision A decimal string that specifies the minimum
number of digits to appear for the d, H, I, j,
m, M, o, S, U, w, W, y, and Y conversion formats
and the maximum number of characters to used
from the a, A, b, B, c, D, E, h, n, N, p, r, t,
T, x, X, Z, and % conversion formats.
format-code A single character that specifies the date and
time conversion to perform. The following list
describes the conversion code characters (shown
with a percent sign):
%a The short day of the week is output as a
string as defined for the current locale
(Mon, for example).
%A The long day of the week is output as
defined for the current locale (Monday, for
example).
%b or h
The short month is output as a string as
defined for the current locale (Jan, for
example).
%B The long month is output as a string as
defined for the current locale (January,
for example).
%c The date and time is output with the short
date and time as defined for the current
locale.
%C The date and time is output with the long
date and time as defined for the current
locale.
%d The day of the month is output as a number
between 01 and 31.
%D The format is fixed to return %m/%d/%y.
(EXAMPLE, 20 Jun 1990 will return
06/20/90.)
%E The locale-dependent combined Emperor/Era
name and year is output.
%H The hour of the day is output as a number
between 00 and 23.
%I The hour of the day is output as a number
between 01 and 12.
%j The Julian day of the year is output as a
number between 001 and 366.
%m The month of the year is output as a number
between 01 and 12.
%M The minute is output as a number between 00
and 59.
%n Only a new-line character is output.
%N The locale-dependent Emperor/Era name is
output.
%o The locale-dependent Emperor/Era year is
output.
%p The A.M. or P.M. indicator is output as a
string specified for the current locale.
%r The time in a.m./p.m. notation is output,
according to British/US conventions
(%I:%M:%S [AM|PM]).
%S The second is output as a number between 00
and 61.
%t Only a tab character is output.
%T The time is output as HH:MM:SS.
%U The week number of the year (Sunday as the
first day of the week). Output format is a
decimal number (00, 53)
%w The day of the week is output as a number
between 0 (Sunday) and 6.
%W The week number of the year (Monday as the
first day of the week). Output format is a
decimal number (00, 53)
%x The short date is output in the Format
specified for the current locale.
%X The time is output in the format specified
for the current locale.
%y The year is output as a number (without the
century) between 00 and 99.
%Y The year is output as a number (with the
century) between 0000 and 9999.
%Z The (standard or daylight-saving) time zone
name is output as a string from the
environment variable TZ (CDT, for example).
%% The % (percent) character is output.
When a conversion code character is not one of the above,
the behavior of this function is undefined.
NOTES
AES Support Level:
Full use
The %S seconds field can contain a value up to 61 seconds
rather than up to 59 seconds to allow leap seconds that are
sometimes added to years to keep clocks in correspondence
with the solar year.
RETURN VALUES
When the total number of resulting characters, including the
terminating null character, is not more than maxsize, the
strftime() function returns the number of characters written
into the array pointed to by the s parameter. The returned
value does not include the terminating null character. Oth-
erwise, a value of (size_t) 0 (zero) is returned and the
contents of the array are undefined.
RELATED INFORMATION
Functions: ctime(3), setlocale(3)
Acknowledgement and Disclaimer