strftime
—flexible calendar time formatter#include <time.h> size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timp);
Description
strftime
converts a struct tm
representation of the time (at
timp) into a null-terminated string, starting at s and occupying
no more than maxsize characters.
You control the format of the output using the string at format.
*
format can contain two kinds of specifications: text to be
copied literally into the formatted string, and time conversion
specifications. Time conversion specifications are two- and
three-character sequences beginning with `%
' (use `%%
' to
include a percent sign in the output). Each defined conversion
specification selects only the specified field(s) of calendar time
data from *
timp, and converts it to a string in one of the
following ways:
%a
%A
Sunday
',
`Monday
', `Tuesday
', `Wednesday
', `Thursday
',
`Friday
', or `Saturday
'. [tm_wday]
%b
%B
January
', `February
',
`March
', `April
', `May
', `June
', `July
',
`August
', `September
', `October
', `November
',
`December
'. [tm_mon]
%c
"%a %b %e %H:%M:%S %Y"
' (example "Mon Apr 01 13:13:13
1992"). [tm_sec, tm_min, tm_hour, tm_mday, tm_mon, tm_year, tm_wday]
%C
%C%y
' is equivalent to `%Y
'. [tm_year]
%d
01
' to
`31
'). [tm_mday]
%D
"%m/%d/%y"
'.
[tm_mday, tm_mon, tm_year]
%e
1
' to `31
'). [tm_mday]
%Ex
x
. But in the "C" locale supported by newlib,
it is ignored, and treated as %x
.
%F
"%Y-%m-%d"
'. [tm_mday, tm_mon, tm_year]
%g
00
' to `99
'). [tm_year, tm_wday, tm_yday]
%G
%h
%H
00
' to `23
'). [tm_hour]
%I
01
' to `12
'). [tm_hour]
%j
001
' to `366
'). [tm_yday]
%k
0
' to `23
'). Non-POSIX extension. [tm_hour]
%l
1
' to `12
'). Non-POSIX extension. [tm_hour]
%m
01
' to `12
').
[tm_mon]
%M
00
' to `59
'). [tm_min]
%n
\n
').
%Ox
x
. But in the "C" locale supported by newlib, it
is ignored, and treated as %x
.
%p
AM
' or `PM
' as appropriate. [tm_hour]
%r
%R
%S
00
' to `60
'). The
value 60 accounts for the occasional leap second. [tm_sec]
%t
\t
').
%T
%u
1
' to
`7
'). [tm_wday]
%U
00
' to `53
'). See also %W
. [tm_wday, tm_yday]
%V
01
' to `53
'). See also %G
. [tm_year, tm_wday, tm_yday]
%w
0
' to `6
').
[tm_wday]
%W
00
' to `53
'). [tm_wday, tm_yday]
%x
%X
%y
00
' to `99
'). [tm_year]
%Y
%C%y
. It will always have at least four
characters, but may have more. The year is accurate even when tm_year
added to the offset of 1900 overflows an int. [tm_year]
%z
%Z
%%
%
'.
Returns
When the formatted time takes up no more than maxsize characters,
the result is the length of the formatted string. Otherwise, if the
formatting operation was abandoned due to lack of room, the result is
0
, and the string starting at s corresponds to just those
parts of *
format that could be completely filled in within the
maxsize limit.
Portability
ANSI C requires strftime
, but does not specify the contents of
*
s when the formatted string would require more than
maxsize characters. Unrecognized specifiers and fields of
timp
that are out of range cause undefined results. Since some
formats expand to 0 bytes, it is wise to set *
s to a nonzero
value beforehand to distinguish between failure and an empty string.
This implementation does not support s
being NULL, nor overlapping
s
and format
.
strftime
requires no supporting OS subroutines.