strftime(S-osr5)

strftime, cftime, ascftime -- convert date and time to string

Syntax

cc ... -lc

#include <time.h>

size_t strftime(char *s, size_t maxsize, const char *format,
    const struct tm *timeptr);

int cftime(char *s, const char *format, const time_t *clock);

int ascftime(char *s, const char *format, const struct tm *timeptr);

Description

strftime(S-osr5), ascftime(S-osr5), and cftime(S-osr5) 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.

For cftime( ) and asctime( ), if format is (char *)0, then the locale's default format is used. If the environment variable CFTIME is defined and nonempty, it is used as the default format; otherwise %N is used.

Each directive is replaced by appropriate characters as described by 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: abbreviated weekday name
%A: full weekday name
%b: abbreviated month name
%B: full month name
%c: basic date and time representation
%C: number of the century (00 - 99)
%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 below.
%h: 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: same as new-line
%N: default date and time representation
%O: a modifier character used in association with certain conversion specifiers; see below
%p: equivalent of either AM or PM
%r: 12-hour time (including %p)
%R: same as %H:%M
%S: seconds (00 - 61), allows for leap seconds
%t: same as a tab
%T: same 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 (for example, 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 (Monday = 1)
%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 %C) 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(C)
%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

If the alternative format or specification for the above specifiers does not exist for the current locale, the behavior will be as if the unmodified specifier was used.

Selecting the output's language

By default, the output of strftime( ), cftime( ), and ascftime( ) appear as in the C 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 in setlocale(S-osr5).

Timezone

The timezone is taken from the environment variable TZ (see ctime(S-osr5) for a description of TZ).

Return values

strftime( ), cftime( ), and ascftime( ) return the number of characters placed into the array pointed to by s not including the terminating null character.

If more than maxsize characters would have been placed into the array, strftime( ) returns zero and the array content is indeterminate. If strftime( ), cftime( ), or ascftime( ) overrun the size of the array, the behavior is undefined.

Warning

cftime(S-osr5) and ascftime(S-osr5) are obsolete. strftime(S-osr5) should be used instead.

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, in the C locale.

Files

/usr/lib/lang/language/territory/codeset/time: file containing locale-specific date and time information. See locale(M) for further information about language, territory, and codeset.

Standards conformance

strftime(S-osr5) is conformant with:

ANSI X3.159-1989 Programming Language -- C ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .

cftime(S-osr5) and ascftime(S-osr5) are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.