strftime

Uses date and time information stored in a tm structure, to create an output string. The format of the output string is controlled by a format string.

Format

#include  <time.h>

size_t strftime  (char *s, size_t maxsize,
                 const char *format, const struct tm
                 *timeptr);

Arguments

s

A pointer to the resultant string.

maxsize

The maximum number of bytes to be stored in the resultant string.

format

A pointer to a string that controls the format of the output string.

timeptr

A pointer to the local time structure. The tm structure is defined in the <time.h> header file.

Description

The format string consists of zero or more conversion specifications and ordinary characters. All ordinary characters (including the terminating null character) are copied unchanged into the output string. A conversion specification defines how data in the tm structure is formatted in the output string.

A conversion specification consists of a percent (%) character followed by one or more optional characters (see Table 9), and concluding with a conversion specifier (see Table 10). If any of the optional characters listed in Table 9 are specified, they must appear in the order shown in the table.

The strftimefunction behaves as if it called tzset.

Table 9 Optional Elements of strftime Conversion Specifications

Note that the list of conversion specifications in Table 9 are extensions to the XPG4 specification.

Table 10 lists the conversion specifiers. The strftime function uses fields in the LC_TIME category of the program's current locale to provide a value. For example, if %B is specified, the function accesses the mon field in LC_TIME to find the full month name for the month specified in the tm structure. The result of using invalid conversion specifiers is undefined.

Table 10 strftime Conversion Specifiers

Return Values

x	The number of characters placed into the array pointed to by s, not including the terminating null character.
0	Indicates an error occurred. The contents of the array are indeterminate.

Example

#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <locale.h>
#include <errno.h>

#define NUM_OF_DATES  7
#define BUF_SIZE 256

/*
 * This program formats a number of different dates, once using the C
 * locale and then using the fr_FR.ISO8859-1 locale.  Date and time
 * formatting is done using strftime().
 */

main()
{
    int  count, i;
    char buffer[BUF_SIZE];
    struct tm *tm_ptr;
    time_t time_list[NUM_OF_DATES] = {500, 68200000, 694223999, 694224000,
                                          704900000, 705000000, 705900000};

    /* Display dates using the C locale */
    printf("\nUsing the C locale:\n\n");

    setlocale(LC_ALL, "C");

    for (i=0; i < NUM_OF_DATES; i++) {
        /* Convert to a tm structure */
        tm_ptr = localtime(&time_list[i]);

        /* Format the date and time */
        count = strftime(buffer, BUF_SIZE, "Date: %A %d %B %Y%nTime: %T%n%n",
                                                                tm_ptr);
        if (count == 0) {
            perror("strftime");
            exit(EXIT_FAILURE);
        }

        /* Print the result */
        printf(buffer);
    }

    /* Display dates using the fr_FR.ISO8859-1 locale */
    printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n");

    setlocale(LC_ALL, "fr_FR.ISO8859-1");

    for (i=0; i < NUM_OF_DATES; i++) {
        /* Convert to a tm structure */
        tm_ptr = localtime(&time_list[i]);

        /* Format the date and time */
        count = strftime(buffer, BUF_SIZE, "Date: %A %d %B %Y%nTime: %T%n%n",
        tm_ptr);
        if (count == 0) {
            perror("strftime");
            exit(EXIT_FAILURE);
        }

        /* Print the result */
        printf(buffer);
    }
}

Running the example program produces the following result:

Using the C locale:

Date: Thursday 01 January 1970
Time: 00:08:20

Date: Tuesday 29 February 1972
Time: 08:26:40

Date: Tuesday 31 December 1991
Time: 23:59:59

Date: Wednesday 01 January 1992
Time: 00:00:00

Date: Sunday 03 May 1992
Time: 13:33:20

Date: Monday 04 May 1992
Time: 17:20:00

Date: Friday 15 May 1992
Time: 03:20:00

Using the fr_FR.ISO8859-1 locale:

Date: jeudi 01 janvier 1970
Time: 00:08:20

Date: mardi 29 février 1972
Time: 08:26:40

Date: mardi 31 décembre 1991
Time: 23:59:59

Date: mercredi 01 janvier 1992
Time: 00:00:00

Date: dimanche 03 mai 1992
Time: 13:33:20

Date: lundi 04 mai 1992
Time: 17:20:00

Date: vendredi 15 mai 1992
Time: 03:20:00