strptime() — Date and time conversion

Standards

Format

#include <time.h>

char *strptime(const char * __restrict__ buf, const char * __restrict__ fmt, 
               struct tm * __restrict__ tm);

General description

The strptime() function converts the character string pointed to by buf to values that are stored in the tm structure pointed to by tm, using the format specified by fmt. Only the fields in the tm structure for which there is a corresponding format item in fmt are updated by the strptime() function. Therefore, for a valid and conforming tm structure, provide strptime() with a format and data that completely specify the date and time being converted.

To avoid infringing on the user's name space, this nonstandard function has two names. One name is prefixed with two underscore characters, and one name is not. The name without the prefix underscore characters is exposed only when you use LANGLVL(EXTENDED).

To use this function, you must either invoke the function using its external entry point name (that is, the name that begins with two underscore characters), or compile with LANGLVL(EXTENDED). When you use LANGLVL(EXTENDED) any relevant information in the header is also exposed.

The format is composed of zero or more directives. Each directive is composed of one of the following: one or more white space characters (as specified by the isalnum() to isxdigit() function), an ordinary character other than a percent sign (%) or white space character, or a conversion specification. Each conversion specification is composed of a percent sign followed by a conversion character that specifies the replacement required. There must be a white space character or other nonalphanumeric character between any two conversion specifications.

A directive composed of white space characters is executed by scanning input up to the first character that is not white space (which remains unscanned) or until no more characters can be scanned.

A directive that is an ordinary character is executed by scanning the next character from the buffer. If the character scanned from the buffer differs from the one comprising the directive, the directive fails, and the differing and subsequent characters remain unscanned.

A series of directives composed or %n, %t, white space characters or any combination is executed by scanning up to the first character that is not white space (which remains unscanned), or until no more characters can be scanned.

Any other conversion specification is executed by scanning characters until a character matching the next directive is scanned, or until no more characters can be scanned. These characters, excepting the one matching the next directive, are then compared to the locale values associated with the conversion specifier. If a match is found, values for the appropriate tm structure members are set to values corresponding to the locale information. Case is ignored when matching items in buf, such as month or weekday names. If no match is found, strptime() fails and no more characters are scanned.

Returned value

If successful, strptime() returns a pointer to the character following the last character parsed.

If unsuccessful, strptime() returns a NULL pointer.

Example

⁄* CELEBS48 *⁄                                   
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
#include <time.h>                                                               
#include <localdef.h>                                                           
                                                                                
int main(void)                                                                  
{                                                                               
   struct tm xmas;                                                              
                                                                                
   if (strptime("12⁄25⁄93 13:30:00", "%D %T", &xmas) == NULL) {                 
      printf("strptime() failed.\n");                                           
      exit(1);                                                                  
   }                                                                            
                                                                                
   printf("tm_sec  =%3d\n", xmas.tm_sec  );                                     
   printf("tm_min  =%3d\n", xmas.tm_min  );                                     
   printf("tm_hour =%3d\n", xmas.tm_hour );                                     
   printf("tm_mday =%3d\n", xmas.tm_mday );                                     
   printf("tm_mon  =%3d\n", xmas.tm_mon  );                                     
   printf("tm_year =%3d\n", xmas.tm_year );                                     
   printf("tm_wday =%3d\n", xmas.tm_wday );                                     
   printf("tm_yday =%3d\n", xmas.tm_yday );                                     
}                                                                               

tm_sec  =  0
tm_min  = 30
tm_hour = 13
tm_mday = 25
tm_mon  = 11
tm_year = 93
tm_wday =  0
tm_yday =358

Related information

• time.h