 |
» |
|
|
|
NAMEstrftime() — 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
); DESCRIPTIONThe
strftime()
function 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). DirectivesThe 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. - %C
The century number (the year divided by 100 and truncated to an integer)
as a decimal number [00-99]. - %d
Day of the month as a decimal number [01,31]. - %D
Equivalent to the directive string
%m/%d/%y. - %e
Day of the month as a decimal number [1,31]; a single digit is preceded by a space. - %h
Equivalent to
%b. - %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
The New-line character. - %p
Locale's equivalent of either
AM
or
PM. - %r
The time in AM and PM notation; in the POSIX locale this is equivalent to
%I:%M:%S %p. - %R
The time in 24 hour notation
(%H:%M). - %S
Second as a decimal number [00,61]. - %t
The Tab character. - %T
The time in hours, minutes, and seconds
(%H:%M:%S). - %u
The weekday as a decimal number [1(Monday),7]. - %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. - %V
The week number of the year (Monday as the first day of the week) as a
decimal number [01,53]. If the week containing January 1st has four or more
days in the new year, then it is considered week 1; otherwise,
it is the last week of the previous year, and the next week is week 1. - %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 Monday
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 percent (%) character.
The following directives are provided for backward compatibility
with the directives supported by
date(1)
and the
ctime(3C)
functions. These directives may be removed in a future
release.
It is recommended that the directives above
be used in preference to those below.
- %E
Locale's combined Emperor/Era name and year (use
%EC%Ey
instead). - %F
Locale's full month name (use
%B
instead). - %N
Locale's Emperor/Era name (use
%EC
instead). - %o
Locale's Emperor/Era year (use
%Ey
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. Modified Conversion SpecifiersSome conversion specifiers can be modified by the E or O modifer characters
to indicate that an alternative format or specification should be used rather
than the one normally used by the unmodified conversion specifier. If the
alternative format or specification does not exist for the current locale,
the behavior will be as if the unmodified conversion specification were used.
Alternative numeric symbols refers to those symbols defined by the
ALT_DIGIT
(see
langinfo(5))
in the locale.
- %Ec
The locales alternative appropriate date and time representation. - %EC
The name of the base year (period/Emperor/Era) in the locale's alternative
representation. - %Ex
The locale's alternative date representation - %EX
The locale's alternative time representation. - %Ey
The offset from
%EC
(year only) in the locale's alternative
representation. - %EY
The full alternative year representation. - %Od
The day of the month, using the locale's alternative numeric symbols,
filled as needed with leading zeros if there is any alternative symbol
for zero, otherwise with leading spaces. - %Oe
the day of the month, using the locale's alternative numeric symbols, filled as needed with leading spaces. - %OH
The hour (24-hour clock) using the locale's alternative numeric symbols. - %OI
The hour (12-hour clock) using the locale's alternative numeric symbols. - %Om
The month using the locale's alternative numeric symbols. - %OM
The minutes using the locale's alternative numeric symbols. - %OS
The seconds using the locale's alternative numeric symbols. - %Ou
The weekday as a number in the locale's alternative representation (Monday=1). - %OU
The week number of the year
(Sunday as the first day of the week, rules corresponding to
%U)
using the locale's alternative numeric symbols. - %OV
The week number of the year
(Monday as the first day of the week, rules corresponding to
%V)
using that locale's alternative numeric symbols. - %Ow
The number of the weekday (Sunday=0) using the locale's alternative numeric symbols. - %OW
The week number of the year (Monday as the first day of the week) using the locale's alternative numeric symbols. - %Oy
The year (offset from
%C)
in the locale's alternative representation and using the locale's alternative symbols.
Field Width and PrecisionAn 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. - .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 bytes 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 bytes than specified
by the precision, excess bytes 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 INFLUENCESLocaleThe
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. If both
ALT_DIGITS
and
ALT_DIGIT
is defined for the locale,
ALT_DIGITS
will take precedence over
ALT_DIGIT. Environment VariablesTZ
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 SupportSingle- and multi-byte character code sets are supported. APPLICATION USAGEstrftime()
is thread-safe. It is not async-cancel-safe. RETURN VALUEIf the total number of resulting bytes
including the terminating null byte is not more than
maxsize,
strftime()
returns the number of bytes placed
into the array pointed to by
s,
not including the terminating null byte.
Otherwise, zero is returned
and the contents of the array are indeterminate. EXAMPLESIf the
timeptr
argument contains the following values:
timeptr->tm_sec = 4;
timeptr->tm_min = 9;
timeptr->tm_hour = 15;
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: * The directives used in these examples are not affected by the
LC_TIME
category of the locale. WARNINGSIf 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). AUTHORstrftime()
was developed by HP. STANDARDS CONFORMANCEstrftime(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C |
