getdate Subroutine

Purpose

Convert user format date and time.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>

struct tm *getdate (const char *string)
extern int getdate_err

Description

The getdate subroutine converts user definable date and/or time specifications pointed to by string, into a struct tm. The structure declaration is in the time.h header file (see ctime subroutine).

User supplied templates are used to parse and interpret the input string. The templates are contained in text files created by the user and identified by the environment variable DATEMSK. The DATEMSK variable should be set to indicate the full pathname of the file that contains the templates. The first line in the template that matches the input specification is used for interpretation and conversation into the internal time format.

The templates should follow a format where complex field descriptors are preceded by simpler ones. For example:

%M
%H:%M
%m/%d/%y
%m/%d/%y %H:%M:%S

The following field descriptors are supported:

Item Description
%% Same as %.
%a Abbreviated weekday name.
%A Full weekday name.
%b Abbreviated month name.
%B Full month name.
%c Locale's appropriate date and time representation.
%C Century number (00-99; leading zeros are permitted but not required)
%d Day of month (01 - 31: the leading zero is optional.
%e Same as %d.
%D Date as %m/%d/%y.
%h Abbreviated month name.
%H Hour (00 - 23)
%I Hour (01 - 12)
%m Month number (01 - 12)
%M Minute (00 - 59)
%n Same as \n.
%p Locale's equivalent of either AM or PM.
%r Time as %I:%M:%S %p
%R Time as %H: %M
%S Seconds (00 - 61) Leap seconds are allowed but are not predictable through use of algorithms.
%t Same as tab.
%T Time as %H: %M:%S
%w Weekday number (Sunday = 0 - 6)
%x Locale's appropriate date representation.
%X Locale's appropriate time representation.
%y Year within century.
Note: When the environment variable XPG_TIME_FMT=ON, %y is the year within the century. When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969 to 1999, inclusive); values in the range 00-68 refer to 2000 to 2068, inclusive.
%Y Year as ccyy (such as 1986)
%Z Time zone name or no characters if no time zone exists. If the time zone supplied by %Z is not the same as the time zone getdate subroutine expects, an invalid input specification error will result. The getdate subroutine calculates an expected time zone based on information supplied to the interface (such as hour, day, and month).

The match between the template and input specification performed by the getdate subroutine is case sensitive.

The month and weekday names can consist of any combination of upper and lower case letters. The used can request that the input date or time specification be in a specific language by setting the LC_TIME category (See the setlocale subroutine).

Leading zero's are not necessary for the descriptors that allow leading zero's. However, at most two digits are allowed for those descriptors, including leading zero's. Extra whitespace in either the template file or in string is ignored.

The field descriptors %c, %x, and %X will not be supported if they include unsupported field descriptors.

Example 1 is an example of a template. Example 2 contains valid input specifications for the template. Example 3 shows how local date and time specifications can be defined in the template.

The following rules apply for converting the input specification into the internal format:

Return Values

Upon successful completion, the getdate subroutine returns a pointer to struct tm; otherwise, it returns a null pointer and the external variable getdate_err is set to indicate the error.

Error Codes

Upon failure, a null pointer is returned and the variable getdate_err is set to indicate the error.

The following is a complete list of the getdate_err settings and their corresponding descriptions:

Item Description
1 The DATEMSK environment variable is null or undefined.
2 The template file cannot be opened for reading.
3 Failed to get file status information.
4 The template file is not a regular file.
5 An error is encountered while reading the template file.
6 Memory allocation failed (not enough memory available.
7 There is no line in the template that matches the input.
8 Invalid input specification, Example: February 31 or a time is specified that can not be represented in a time_t (representing the time in seconds since 00:00:00 UTC, January 1, 1970).

Examples

  1. The following example shows the possible contents of a template: 
    %m
%A %B %d, %Y, %H:%M:%S
%A
%B
%m/%d/%y %I %p
%d, %m, %Y %H:%M
at %A the %dst of %B in %Y
run job at %I %p, %B %dnd
&A den %d. %B %Y %H.%M Uhr
  2. The following are examples of valid input specifications for the template in Example 1: 
    getdate ("10/1/87 4 PM")
getdate ("Friday")
getdate ("Friday September 18, 1987, 10:30:30")
getdate ("24,9,1986 10:30")
getdate ("at monday the 1st of december in 1986")
getdate ("run job at 3 PM. december 2nd")
    If the LC_TIME category is set to a German locale that includes freitag as a weekday name and oktober as a month name, the following would be valid: 
    getdate ("freitag den 10. oktober 1986 10.30 Uhr")
  3. The following examples shows how local date and time specification can be defined in the template.
    Invocation Line in Template
    getdate ("11/27/86") %m/%d/%y
    getdate ("27.11.86"0 %d.%m.%y
    getdate ("86-11-27") %y-%m-%d
    getdate ("Friday 12:00:00") %A %H:%M:%S
  4. The following examples help to illustrate the above rules assuming that the current date Mon Sep 22 12:19:47 EDT 1986 and the LC_TIME category is set to the default "C" locale.
    Input Line in Template Date
    Mon %a Mon Sep 22 12:19:47 EDT 1986
    Sun %a Sun Sep 28 12:19:47 EDT 1986
    Fri %a Fri Sep 26 12:19:47 EDT 1986
    September %B Mon Sep1 12:19:47 EDT 1986
    January %B Thu Jan 1 12:19:47 EDT 1986
    December %B Mon Dec 1 12:19:47 EDT 1986
    Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986
    Jan Fri %b %a Fri Jan 2 12:19:47 EDT 1986
    Dec Mon %b %a Mon Dec 1 12:19:47 EDT 1986
    Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EDT 1986
    Fri 9 %a %H Fri Sep 26 12:19:47 EDT 1986
    Feb 10:30 %b %H: %S Sun Feb 1 12:19:47 EDT 1986
    10:30 %H: %M Tue Sep 23 12:19:47 EDT 1986
    13:30 %H: %M Mon Sep 22 12:19:47 EDT 1986