strftime(3C)


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, const 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.

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
date and time representation as used by date.

%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.ile.


%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.

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.

Timezone

The timezone is taken from the environment variable TZ [see ctime(3C) 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. Otherwise, zero is returned and the contents of the array are indeterminate. 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.

Files


/usr/lib/locale/``locale''/LC_TIME
file containing locale-specific date and time information

Usage

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.

For the following Era related definitions for LC_TIME:

   era_d_fmt "%EY%mgatsu%dnichi (%a)"
   era_d_fmt "The alternative time format is %h (%S) in %EC"
   era_d_t_fmt "%EY%mgatsu%dnichi (%a) %T"
   era "+:2:1990/01/01:+*:Heisei:%EC%Eynen";
         "+:1:1989/01/08:1989/12/31:Heisei:%ECgannen";
         "+:2:1927/01/01:1989/01/07:Shouwa:%EC%Eynen";
         "+:1:1926/12/25:1926/12/31:Shouwa:%ECgannen";
         "+:2:1913/01/01:1926/12/24:Taishou:%EC%Eynen";
         "+:1:1912/07/30:1912/12/31:Taishou:%ECgannen";
         "+:2:1869/01/01:1912/07/29:Meiji:%EC%Eynen";
         "+:1:1868/09/08:1868/12/31:Meiji:%ECgannen";
         "-:1868:1868/09/07:-*: :%Ey"

For August 1st 1912, with the LC_TIME locale category set as above:

   strftime(str, strsize, "%Ey", tmptr);

would result in str containing ``"01"''.

   strftime(str, strsize, "%Ey %EC %Ex", tmptr);

would result in str containing ``"Taishougannen Taishou Taishougannen08gatsu01nichi (Sun)"''.

   strftime(str, strsize, "%EX", tmptr);

would result in str containing ``"The alternative time format is Aug (01) in Taishou"''.

References

ctime(3C), environ(5), getenv(3C), setlocale(3C), strftime(4), timezone(4)

Notices

cftime and ascftime are obsolete. strftime should be used instead.
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004