strftime() -- Time Function (libc)

Format locale-specific time
#include <time.h>
size_t strftime(string, maximum, format, brokentime)
char *string; size_t maximum; const char *format;
        const struct tm *brokentime;

The function strftime() provides a locale-specific way to print the current
time and  date.  It also gives  you an easy way to  shuffle the elements of
date and time into a string that suits your preferences.

strftime() references  the portion  of the locale  that is affected  by the
calls

    setlocale(LC_TIME, locale);

or

    setlocale(LC_ALL, locale);

For more information on setting locales, see the entry for localization.

string points to the region of memory into which strftime() writes the date
and time string it generates.   maximum is the maximum number of characters
that  can  be written  into  string.  string should  point  to  an area  of
allocated memory  at least maximum+1  bytes long; if it  does not, reserved
portions of memory may be overwritten.

brokentime points to a structure of type tm, which contains the broken-down
time.  This structure must first  be initialized by either of the functions
localtime() or gmtime().

Finally, format  points to  a string that  contains one or  more conversion
specifications, which guide strftime() in building its output string.  Each
conversion specification  is introduced by the percent  sign `%'.  When the
output string  is built, each  conversion specification is  replaced by the
appropriate time element.  Characters within  format that are not part of a
conversion specification are copied into string; to write a literal percent
sign, use ``%%''.

strftime() recognizes the following conversion specifiers:

a  The locale's abbreviated name for the day of the week.
A  The locale's full name for the day of the week.
b  The locale's abbreviated name for the month.
B  The locale's full name for the month.
c  The locale's default representation for the date and time.
d  The day of the month as an integer (01 through 31).
H  The hour as an integer (00 through 23).
I  The hour as an integer (01 through 12).
j  The day of the year as an integer (001 through 366).
m  The month as an integer (01 through 12).
M  The minute as an integer (00 through 59).
p  The locale's way of indicating  morning or afternoon (e.g, in the United
   States, ``AM'' or ``PM'').
S  The second as an integer (00 through 59).
U  The week of the year as an integer (00 through 53); regard Sunday as the
   first day of the week.
w  The day  of the week as  an integer (0 through 6);  regard Sunday as the
   first day of the week.
W  The day  of the week as  an integer (0 through 6);  regard Monday as the
   first day of the week.
x  The locale's default representation of the date.
X  The locale's default representation of the time.
y  The year within the century (00 through 99).
Y  The full year, including century.
z  The name of the locale's time  zone.  If no time zone can be determined,
   print a null string.

Use  of any  conversion specifier  other  than the  ones listed  above will
result in undefined behavior.

If the  number of characters written  into string is less  than or equal to
maximum,  then strftime()  returns the number  of characters  written.  If,
however,  the number  of  characters to  be written  exceeds maximum,  then
strftime() returns zero  and the contents of the area  pointed to by string
are indeterminate.

See Also

asctime(),
ctime(),
gmtime(),
libc,
localtime(),
time [overview]
ANSI Standard, §7.12.3.5
POSIX Standard, §8.1

© 2012 by Stephen A. Ness