libc - Formatting Date and Time

File: libc.info Node: Formatting Date and Time Next: TZ Variable Prev: Broken-down Time Up: Calendar 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. *Note 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 (*note 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 (*note 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 *Note Time Functions Example::.

Next: TZ Variable Up: Calendar Time

converted by gnuinfo


Main page of this Linux-oriented web server
This server is maintained by VH