The functions described in this section format time values as strings. These functions are declared in the header file `time.h'.
asctime
function converts the broken-down time value that
brokentime points to into a string in a standard format:
"Tue May 21 13:46:22 1991\n"
The abbreviations for the days of week are: `Sun', `Mon', `Tue', `Wed', `Thu', `Fri', and `Sat'.
The abbreviations for the months are: `Jan', `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and `Dec'.
The return value points to a statically allocated string, which might be
overwritten by subsequent calls to asctime
or ctime
.
(But no other library function overwrites the contents of this
string.)
asctime
but instead of placing the
result in a static buffer it writes the string in the buffer pointed to
by the parameter buffer. This buffer should have at least room
for 16 bytes.
If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns buffer. Otherwise
return NULL
.
ctime
function is similar to asctime
, except that the
time value is specified as a time_t
calendar time value rather
than in broken-down local time format. It is equivalent to
asctime (localtime (time))
ctime
sets the variable tzname
, because localtime
does so. See section Functions and Variables for Time Zones.
ctime
, only that it places the result
in the string pointed to by buffer. It is equivalent to (written
using gcc extensions, see section `Statement Exprs' in Porting and Using gcc):
({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })
If no error occurred the function returns a pointer to the string the
result was written into, i.e., it returns buffer. Otherwise
return NULL
.
sprintf
function (see section 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 section Locales and Internationalization).
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:
_
-
0
^
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
%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
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
%A
%b
%B
%c
%C
%d
01
through 31
).
%D
%m/%d/%y
.
This format is a POSIX.2 extension.
%e
%d
, but padded with blank (range
1
through 31
).
This format is a POSIX.2 extension.
%F
%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 C 9X extension.
%g
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 is a GNU extension.
%G
%Y
, except that if the ISO week number (see
%V
) belongs to the previous or next year, that year is used
instead.
This format is a GNU extension.
%h
%b
.
This format is a POSIX.2 extension.
%H
00
through
23
).
%I
01
through
12
).
%j
001
through 366
).
%k
%H
, but
padded with blank (range 0
through 23
).
This format is a GNU extension.
%l
%I
, but
padded with blank (range 1
through 12
).
This format is a GNU extension.
%m
01
through 12
).
%M
00
through 59
).
%n
%p
%P
%r
%R
%H:%M
.
This format is a GNU extension.
%s
%S
00
through 60
).
%t
%T
%H:%M:%S
.
This format is a POSIX.2 extension.
%u
1
through
7
), Monday being 1
.
This format is a POSIX.2 extension.
%U
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
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.
%w
0
through
6
), Sunday being 0
.
%W
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
%X
%y
00
through
99
). This is equivalent to the year modulo 100.
%Y
1
are numbered 0
, -1
, and so on.
%z
-0600
or +0100
), or nothing if no time zone is
determinable.
This format is 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 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 content of the array
s is indetermined. 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 section Time Functions Example.
Go to the first, previous, next, last section, table of contents.