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 asctime or ctime. (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 section Functions and Variables for Time Zones.

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 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, which are GNU extensions, 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 section 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 date and 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.

%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.

%e

The day of the month like with %d, but padded with blank (range 1 through 31). This format is a POSIX.2 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 is a GNU extension.

%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 is 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.

%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.

%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 is a GNU extension.

%r

The complete time using the AM/PM format of the current locale. This format is a POSIX.2 extension.

%R

The hour and minute in decimal numbers using the format %H:%M. This format is 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 second as a decimal number (range 00 through 60).

%t

A single `\t' (tabulator) character. This format is a POSIX.2 extension.

%T

The time 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.

%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.

%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, but without the time.

%X

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

%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 is a GNU extension.

%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, 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.

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.