strptime

Converts a character string into date and time values that are stored in a tm structure. Conversion is controlled by a format string.

Format

#include  <time.h>

char *strptime  (const char *buf, const char
                *format, struct tm *timeptr);

Arguments

buf

A pointer to the character string to convert.

format

A pointer to the string that defines how the input string is converted.

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 directives. A directive is composed of one of the following:

• One or more white-space characters (as defined by the isspace function). This directive causes the function to read input up to the first character that is not a white-space character.

• Any character other than the percent character (%) or a white-space character. This directive causes the function to read the next character. The character read must be the same as the character that comprises the directive. If the character is different, the function fails.

• A conversion specification. A conversion specification defines how characters in the input string are interpreted as values that are then stored in the tm structure. A conversion specification consists of a percent (%) character followed by a conversion specifier. Table 11 lists the valid conversion specifications.

The strptime function uses fields in the LC_TIME category of the program's current locale to provide a value.

Table 11 strptime Conversion Specifications

Return Values

x	A pointer to the character following the last character parsed.
NULL	Indicates that an error occurred. The contents of the tm structure are undefined.

Example

#include <string.h>
#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 takes a number of date and time strings and converts them
 * into tm structs using strptime().  These tm structs are then passed to
 * strftime() which will reverse the process.  The resulting strings are then
 * compared with the originals and if a difference is found then an error
 * is displayed.
 */

main()
{
    int         count, i;
    char        buffer[BUF_SIZE];
    char        *ret_val;
    struct tm   time_struct;
    char        dates[NUM_OF_DATES][BUF_SIZE] = {
                        "Thursday 01 January 1970 00:08:20",
                        "Tuesday 29 February 1972 08:26:40",
                        "Tuesday 31 December 1991 23:59:59",
                        "Wednesday 01 January 1992 00:00:00",
                        "Sunday 03 May 1992 13:33:20",
                        "Monday 04 May 1992 17:20:00",
                        "Friday 15 May 1992 03:20:00"};

    for (i=0; i < NUM_OF_DATES; i++) {
        /* Convert to a tm structure */
        ret_val = strptime(dates[i], "%A %d %B %Y %T", &time_struct);

        /* Check the return value */
        if (ret_val == (char *)NULL) {
            perror("strptime");
            exit(EXIT_FAILURE);
        }

        /* Convert the time structure back to a formatted string */
        count = strftime(buffer, BUF_SIZE, "%A %d %B %Y %T", &time_struct);

        /* Check the return value */
        if (count == 0) {
            perror("strftime");
            exit(EXIT_FAILURE);
        }

        /* Check the result */
        if (strcmp(buffer, dates[i]) != 0) {
            printf("Error: Converted string differs from the original\n");
        }
        else {
            printf("Successfully converted <%s>\n", dates[i]);
        }
    }
}

Running the example program produces the following result:

Successfully converted <Thursday 01 January 1970 00:08:20>
Successfully converted <Tuesday 29 February 1972 08:26:40>
Successfully converted <Tuesday 31 December 1991 23:59:59>
Successfully converted <Wednesday 01 January 1992 00:00:00>
Successfully converted <Sunday 03 May 1992 13:33:20>
Successfully converted <Monday 04 May 1992 17:20:00>
Successfully converted <Friday 15 May 1992 03:20:00>