The GNU C Library - Formatting Date and Time

Formatting Date and Time

The functions described in this section format time values as strings. These functions are declared in the header file `time.h'.

Function char * asctime (const struct tm *brokentime)

The 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 any of the date and time functions. (But no other library function overwrites the contents of this string.)

Function char * ctime (const time_t *time)

The 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 Time Zone Functions.

Function size_t strftime (char *s, size_t size, const char *template, const struct tm *brokentime)

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, and are 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 date and time representation for the current locale.

%d

The day of the month as a decimal number (range 01 to 31 ).

%H

The hour as a decimal number, using a 24-hour clock (range 00 to 23 ).

%I

The hour as a decimal number, using a 12-hour clock (range 01 to 12 ).

%j

The day of the year as a decimal number (range 001 to 366 ).

%m

The month as a decimal number (range 01 to 12 ).

%M

The minute as a decimal number.

%p

Either `am' or `pm', according to the given time value; or the corresponding strings for the current locale.

%S

The second as a decimal number.

%U

The week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week.

%W

The week number of the current year as a decimal number, starting with the first Monday as the first day of the first week.

%w

The day of the week as a decimal number, Sunday being 0 .

%x

The preferred date representation for the current locale, but without the time.

%X

The preferred time representation for the current locale, but with no date.

%y

The year as a decimal number, but without a century (range 00 to 99 ).

%Y

The year as a decimal number, including the century.

%Z

The time zone or name or 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, the excess characters are discarded. The return value from strftime is the number of characters placed in the array s, not including the terminating null character. If the value equals size, it means that the array s was too small; you should repeat the call, providing a bigger array.

If s is a null pointer, strftime does not actually write anything, but instead returns the number of characters it would have written.

For an example of strftime , see Time Functions Example.