HPUX strftime[3c]
strftime(3C) strftime(3C)
NAME
strftime() - 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
);
DESCRIPTION
strftime() converts the contents of a tm structure (see ctime(3C)) to
a formatted date and time string.
strftime() places 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. A
directive consists of a % character, an optional field width and
precision specification, and a terminating character that determines
the directive's behavior. All ordinary characters (including the
terminating null character are copied unchanged into the array. No
more than maxsize characters are placed into the array. Each
directive is replaced by the appropriate characters as described in
the following list. The appropriate characters are determined by the
program's locale, by the values contained in the structure pointed to
by timeptr, and by the TZ environment variable (see External
Influences below).
Directives
The following directives, shown without the optional field width and
precision specification, are replaced by the indicated characters:
%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.
%d Day of the month as a decimal number [01,31].
%E Locale's combined Emperor/Era name and year.
%H Hour (24-hour clock) as a decimal number [00,23].
%I Hour (12-hour clock) as a decimal number [01,12].
%j Day of the year as a decimal number [001,366].
%m Month as a decimal number [01,12].
%M Minute as a decimal number [00,59].
%n New-line character.
%N Locale's Emperor/Era name.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
strftime(3C) strftime(3C)
%o Locale's Emperor/Era year.
%p Locale's equivalent of either AM or PM.
%S Second as a decimal number [00,61].
%t Tab character.
%U Week number of the year (Sunday as the first day of the
week) as a decimal number [00,53]. All days in a new
year preceding the first Sunday are considered to be in
week 0.
%w Weekday as a decimal number [0(Sunday),6].
%W Week number of the year (Monday as the first day of the
week) as a decimal number [00,53]. All days in a new
year preceding the first Sunday are considered to be in
week 0.
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year without century as a decimal number [00,99].
%Y Year with century as a decimal number.
%Z Time zone name (or by no characters if no time zone
exists).
%% %
The following directives are provided for backward compatibility with
the directives supported by date(1) and the ctime(3C) functions. It
is recommended that the directives above be used in preference to
those below.
%D Date in usual U.S. format (%m/%d/%y) (use %x instead).
%F Locale's full month name (use %B instead).
%h Locale's abbreviated month name (use %b instead).
%r Time in 12-hour U.S. format (%I:%M:%S [AM|PM]) (use %X
instead).
%T Time in 24-hour U.S. format (%H:%M:%S) (use %X
instead).
%z Time zone name (or by no characters if no time zone
exists) (use %Z instead).
If a directive is not one of the above, the behavior is undefined.
Field Width and Precision
An optional field width and precision specification can immediately
follow the initial % of a directive in the following order:
[-|0]w the decimal digit string w specifies a minimum field
width in which the result of the conversion is right-
or left-justified. It is right-justified (with space
padding) by default. If the optional flag `-' is
specified, it is left-justified with space padding on
the right. If the optional flag `0' is specified, it
is right-justified and padded with zeros on the left.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
strftime(3C) strftime(3C)
.p the decimal digit string p specifies the minimum number
of digits to appear for the d, H, I, j, m, M, o, S, U,
w, W, y and Y directives, and the maximum number of
characters to be used from the a, A, b, B, c, D, E, F,
h, n, N, p, r, t, T, x, X, z, Z, and % directives. In
the first case, if a directive supplies fewer digits
than specified by the precision, it will be expanded
with leading zeros. In the second case, if a directive
supplies more characters than specified by the
precision, excess characters will truncated on the
right.
If no field width or precision is specified for a d, H, I, m, M, S, U,
W, y, or j directive, a default of .2 is used for all but j for which
.3 is used.
EXTERNAL INFLUENCES
Locale
The LC_TIME category determines the characters to be substituted for
those directives described above as being from the locale.
The LC_CTYPE category determines the interpretation of the bytes
within format as single and/or multi-byte characters.
The LC_NUMERIC category determines the characters used to form numbers
for those directives that produce numbers in the output. If
ALT_DIGITS (see langinfo(5)) is defined for the locale, the characters
so specified are used in place of the default ASCII characters.
Environment Variables
TZ determines the time zone name substituted for the %Z and %z
directives. The time zone name is determined by calling the function
tzset() which sets the external variable tzname (see ctime(3C)).
International Code Set Support
Single- and multi-byte character code sets are supported.
RETURN VALUE
If the total number of resulting characters including the terminating
null character is not more than maxsize, strftime() returns 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.
EXAMPLES
If the timeptr argument contains the following values:
timeptr->tm_sec = 4;
timeptr->tm_min = 9;
timeptr->tm_hour = 15;
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
strftime(3C) strftime(3C)
timeptr->tm_mday = 4;
timeptr->tm_mon = 6;
timeptr->tm_year = 88;
timeptr->tm_wday = 1;
timeptr->tm_yday = 185;
timeptr->tm_isdst = 1;
the following combinations of the LC_TIME category and format strings
produce the indicated output:
lll. LC_TIME format string output
american %x Mon, Jul 4, 1988 german %x Mo., 4. Juli 1988
american %X 03:09:04 PM french %X 15h09 04
any- %H:%M:%S 15:09:04 any- %.1H:%.1M:%.1S 15:9:4 any- %2.1H:%-
3M:%03.1S 15:9 :004
- The directives used in these examples are not affected by the
LC_TIME category of the locale.
WARNINGS
If the arguments s and format are defined such that they overlap, the
behavior is undefined.
The function tzset() is called upon every invocation of strftime()
(whether or not the time zone name is copied to the output array).
The range of values for %S ([0,61]) extends to 61 to allow for the
occasional one or two leap seconds. However, the system does not
accumulate leap seconds and the tm structure generated by the
functions localtime() and gmtime() (see ctime(3C)) never reflects any
leap seconds.
Results are undefined if values contained in the structure pointed to
by timeptr exceed the ranges defined for the tm structure (see
ctime(3C)) or are not consistent (such as if the tm_yday element is
set to 0, indicating the first day of January, while the tm_mon
element is set to 11, indicating a day in December).
AUTHOR
strftime() was developed by HP.
SEE ALSO
date(1), ctime(3C), getdate(3C), setlocale(3C), environ(5),
langinfo(5), hpnls(5).
STANDARDS CONFORMANCE
strftime(): AES, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992