strftime(3C) SDK R4.11 strftime(3C)
NAME
strftime, cftime, ascftime - convert date and time to string
SYNOPSIS
#include <time.h>
size_t *strftime (char *s, size_t maxsize, const char *format,
const struct tm *timeptr);
int cftime (char *s, char *format, const time_t *clock);
int ascftime (char *s, const char *format, const struct tm
*timeptr);
DESCRIPTION
strftime, ascftime, and cftime place characters into the array
pointed to by s as controlled by the string pointed to by format.
The format string consists of zero or more directives and ordinary
characters. All ordinary characters (including the terminating null
character) are copied unchanged into the array. For strftime, no
more than maxsize characters 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 directive is replaced by appropriate characters as described in
the following list. The appropriate characters are determined by the
LC_TIME category of the program's locale and by the values contained
in the structure pointed to by timeptr for strftime and ascftime, and
by the time represented by clock for cftime.
%% same as %
%a locale's abbreviated weekday name
%A locale's full weekday name
%b locale's abbreviated month name
%B locale's full month name
%c locale's appropriate date and time representation
%C if libxpg4 is linked into the executable, this directive
returns the century number (00 - 99); otherwise, this
directive returns locale's date and time representation as
produced by date(1).
%d day of month ( 01 - 31 )
%D date as %m/%d/%y
%e day of month (1-31; single digits are preceded by a blank)
%E a modifier character used in association with certain
conversion specifiers; see the section Modified Conversion
Specifiers below.
%h locale's abbreviated month name.
%H hour ( 00 - 23 )
%I hour ( 01 - 12 )
%j day number of year ( 001 - 366 )
%m month number ( 01 - 12 )
%M minute ( 00 - 59 )
%n insert a new-line
%N date and time representation as used by date(1)
%O a modifier character used in association with certain
conversion specifiers; see the section Modified Conversion
Specifiers below.
%p locale's equivalent of either AM or PM
%r time as %I:%M:%S [AM|PM]
%R time as %H:%M
%S seconds ( 00 - 61 ), allows for leap seconds
%t insert a tab
%T time as %H:%M:%S
%u weekday number (1 - 7), Monday = 1
%U week number of year ( 00 - 53 ), Sunday is the first day of
week 1
%V week number of the year
%w weekday number ( 0 - 6 ), Sunday = 0
%W week number of year ( 00 - 53 ), Monday is the first day of
week 1
%x locale's appropriate date representation
%X locale's appropriate time representation
%y year within century ( 00 - 99 )
%Y year as ccyy ( e.g. 1986)
%Z time zone name or no characters if no time zone exists
The difference between %U and %W lies in which day is counted as the
first of the week. Week number 01 is the first week in January
starting with a Sunday for %U or a Monday for %W. Week number 00
contains those days before the first Sunday or Monday in January for
%U and %W, respectively.
For %V, if the week containing January 1st has four or more days in
the new year, it is week 1; otherwise, it is week 53 of the preceding
year.
Modified Conversion Specifiers
O modifies the behavior of the following conversion specifiers. The
decimal value is generated using the locale's alternate digit
symbols.
%Od the day of the month, using alternative digit symbols
filled as needed with leading zeros if available;
otherwise, filled with spaces.
%Oe the day of the month, using alternative digit symbols
filled with leading spaces as needed.
%OH the hour (24 hour clock), using alternative digit symbols.
%OI the hour (12 hour clock), using alternative digit symbols.
%Om the month using alternative digit symbols.
%OM the minutes using alternative digit symbols.
%OS the seconds using alternative digit symbols.
%Ou the weekday as a number using alternative digit symbols.
%OU the week number using alternative digit symbols (see rules
for %U).
%OV the week number using alternative digit symbols (see rules
for %V).
%Ow the weekday as a number using alternative digit symbols
(Sunday = 0).
%OW the week number using alternative digit symbols (see rules
for %W).
%Oy the year (offset from the century number) using alternative
digit symbols.
E also modifies the behavior of the following conversion specifiers.
An Era-specific value is generated instead of the normal value.
%Ec Era-specific representation for date and time, as in
date(1).
%EC Era-specific representation for the name of the base
year (period).
%Ex Era-specific representation for the date.
%EX Era-specific representation for the time.
%Ey the offset from %E in the locale's alternative
representation (year only).
%EY the full alternative year representation.
Return Values
If the total number of resulting characters including the terminating
null character is not more than maxsize, strftime, cftime and
ascftime return the number of characters placed into the array
pointed to by s not including the terminating null character.
Otherwise, zero is returned and the contents of the array are
indeterminate. cftime and ascftime return the number of characters
placed into the array pointed to by s not including the terminating
null character.
Selecting the Output's Language
By default, the output of strftime, cftime, and ascftime appear in
the language defined by the "C" locale. This is basically English as
spoken in the United States, but technically is different from the
"En_US" locale. The user can request that the output of strftime,
cftime or ascftime be in a specific language by setting the locale
for category LC_TIME or LC_ALL with setlocale.
Timezone
The timezone is taken from the environment variable TZ [see ctime(3C)
and environ(5) for a description of TZ].
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|ascftime | Y N N |
|cftime | Y Y N |
|strftime | Y N N |
+---------+-----------------------------+
EXAMPLES
The example illustrates the use of strftime. 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 in New Jersey.
strftime (str, strsize, "%A %b %d %j", tmptr)
This results in str containing "Thursday Aug 28 240".
FILES
/usr/lib/locale/language/LC_TIME - file containing locale specific
date and time information
SEE ALSO
reentrant(3), ctime(3C), getenv(3C), setlocale(3C), strftime(4),
timezone(4), environ(5).
NOTE
cftime and ascftime are obsolete. strftime should be used instead.
Licensed material--property of copyright holder(s)