This function is similar to the sprintf function (see Formatted
Input), but the conversion specifications that can appear in the format
template template are specialized for printing components of the date
and time brokentime according to the locale currently specified for
time conversion (see Locales).
Ordinary characters appearing in the template are copied to the
output string s; this can include multibyte character sequences.
Conversion specifiers are introduced by a % character, followed
by an optional flag which can be one of the following. These flags
are all GNU extensions. The first three affect only the output of
numbers:
_
- The number is padded with spaces.
-
- The number is not padded at all.
0
- The number is padded with zeros even if the format specifies padding
with spaces.
^
- The output uses uppercase characters, but only if this is possible
(see Case Conversion).
The default action is to pad the number with zeros to keep it a constant
width. Numbers that do not have a range indicated below are never
padded, since there is no natural width for them.
Following the flag an optional specification of the width is possible.
This is specified in decimal notation. If the natural size of the
output is of the field has less than the specified number of characters,
the result is written right adjusted and space padded to the given
size.
An optional modifier can follow the optional flag and width
specification. The modifiers, which are POSIX.2 extensions, are:
E
- Use the locale's alternate representation for date and time. This
modifier applies to the
%c , %C , %x , %X ,
%y and %Y format specifiers. In a Japanese locale, for
example, %Ex might yield a date format based on the Japanese
Emperors' reigns.
O
- Use the locale's alternate numeric symbols for numbers. This modifier
applies only to numeric format specifiers.
If the format supports the modifier but no alternate representation
is available, it is ignored.
The conversion specifier ends with a format specifier taken from the
following list. The whole % sequence is replaced in the output
string as follows:
%a
- The abbreviated weekday name according to the current locale.
%A
- The full weekday name according to the current locale.
%b
- The abbreviated month name according to the current locale.
%B
- The full month name according to the current locale.
%c
- The preferred calendar time representation for the current locale.
%C
- The century of the year. This is equivalent to the greatest integer not
greater than the year divided by 100.
This format is a POSIX.2 extension and also appears in ISO C99.
%d
- The day of the month as a decimal number (range
01 through 31 ).
%D
- The date using the format
%m/%d/%y .
This format is a POSIX.2 extension and also appears in ISO C99.
%e
- The day of the month like with
%d , but padded with blank (range
1 through 31 ).
This format is a POSIX.2 extension and also appears in ISO C99.
%F
- The date using the format
%Y-%m-%d . This is the form specified
in the ISO 8601 standard and is the preferred form for all uses.
This format is a ISO C99 extension.
%g
- The year corresponding to the ISO week number, but without the century
(range
00 through 99 ). This has the same format and value
as %y , except that if the ISO week number (see %V ) belongs
to the previous or next year, that year is used instead.
This format was introduced in ISO C99.
%G
- The year corresponding to the ISO week number. This has the same format
and value as
%Y , except that if the ISO week number (see
%V ) belongs to the previous or next year, that year is used
instead.
This format was introduced in ISO C99 but was previously available
as a GNU extension.
%h
- The abbreviated month name according to the current locale. The action
is the same as for
%b .
This format is a POSIX.2 extension and also appears in ISO C99.
%H
- The hour as a decimal number, using a 24-hour clock (range
00 through
23 ).
%I
- The hour as a decimal number, using a 12-hour clock (range
01 through
12 ).
%j
- The day of the year as a decimal number (range
001 through 366 ).
%k
- The hour as a decimal number, using a 24-hour clock like
%H , but
padded with blank (range 0 through 23 ).
This format is a GNU extension.
%l
- The hour as a decimal number, using a 12-hour clock like
%I , but
padded with blank (range 1 through 12 ).
This format is a GNU extension.
%m
- The month as a decimal number (range
01 through 12 ).
%M
- The minute as a decimal number (range
00 through 59 ).
%n
- A single
\n (newline) character.
This format is a POSIX.2 extension and also appears in ISO C99.
%p
- Either
AM or PM , according to the given time value; or the
corresponding strings for the current locale. Noon is treated as
PM and midnight as AM .
%P
- Either
am or pm , according to the given time value; or the
corresponding strings for the current locale, printed in lowercase
characters. Noon is treated as pm and midnight as am .
This format was introduced in ISO C99 but was previously available
as a GNU extension.
%r
- The complete calendar time using the AM/PM format of the current locale.
This format is a POSIX.2 extension and also appears in ISO C99.
%R
- The hour and minute in decimal numbers using the format
%H:%M .
This format was introduced in ISO C99 but was previously available
as a GNU extension.
%s
- The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
Leap seconds are not counted unless leap second support is available.
This format is a GNU extension.
%S
- The seconds as a decimal number (range
00 through 60 ).
%t
- A single
\t (tabulator) character.
This format is a POSIX.2 extension and also appears in ISO C99.
%T
- The time of day using decimal numbers using the format
%H:%M:%S .
This format is a POSIX.2 extension.
%u
- The day of the week as a decimal number (range
1 through
7 ), Monday being 1 .
This format is a POSIX.2 extension and also appears in ISO C99.
%U
- The week number of the current year as a decimal number (range
00
through 53 ), starting with the first Sunday as the first day of
the first week. Days preceding the first Sunday in the year are
considered to be in week 00 .
%V
- The ISO 8601:1988 week number as a decimal number (range
01
through 53 ). ISO weeks start with Monday and end with Sunday.
Week 01 of a year is the first week which has the majority of its
days in that year; this is equivalent to the week containing the year's
first Thursday, and it is also equivalent to the week containing January
4. Week 01 of a year can contain days from the previous year.
The week before week 01 of a year is the last week (52 or
53 ) of the previous year even if it contains days from the new
year.
This format is a POSIX.2 extension and also appears in ISO C99.
%w
- The day of the week as a decimal number (range
0 through
6 ), Sunday being 0 .
%W
- The week number of the current year as a decimal number (range
00
through 53 ), starting with the first Monday as the first day of
the first week. All days preceding the first Monday in the year are
considered to be in week 00 .
%x
- The preferred date representation for the current locale.
%X
- The preferred time of day representation for the current locale.
%y
- The year without a century as a decimal number (range
00 through
99 ). This is equivalent to the year modulo 100.
%Y
- The year as a decimal number, using the Gregorian calendar. Years
before the year
1 are numbered 0 , -1 , and so on.
%z
- RFC 822/ISO 8601:1988 style numeric time zone (e.g.,
-0600 or +0100 ), or nothing if no time zone is
determinable.
This format was introduced in ISO C99 but was previously available
as a GNU extension.
A full RFC 822 timestamp is generated by the format
"%a, %d %b %Y %H:%M:%S %z" (or the equivalent
"%a, %d %b %Y %T %z" ).
%Z
- The time zone abbreviation (empty if the time zone can't be determined).
%%
- A literal
% character.
The size parameter can be used to specify the maximum number of
characters to be stored in the array s, including the terminating
null character. If the formatted time requires more than size
characters, strftime returns zero and the contents of the array
s are undefined. Otherwise the return value indicates the
number of characters placed in the array s, not including the
terminating null character.
Warning: This convention for the return value which is prescribed
in ISO C can lead to problems in some situations. For certain
format strings and certain locales the output really can be the empty
string and this cannot be discovered by testing the return value only.
E.g., in most locales the AM/PM time format is not supported (most of
the world uses the 24 hour time representation). In such locales
"%p" will return the empty string, i.e., the return value is
zero. To detect situations like this something similar to the following
code should be used:
buf[0] = '\1';
len = strftime (buf, bufsize, format, tp);
if (len == 0 && buf[0] != '\0')
{
/* Something went wrong in the strftime call. */
...
}
If s is a null pointer, strftime does not actually write
anything, but instead returns the number of characters it would have written.
According to POSIX.1 every call to strftime implies a call to
tzset . So the contents of the environment variable TZ
is examined before any output is produced.
For an example of strftime , see Time Functions Example.
|