getdate(3C)getdate(3C)NAMEgetdate - convert user format date and time
SYNOPSIS
#include <time.h>
struct tm *getdate (const char *string);
extern int getdate_err;
DESCRIPTIONgetdate The getdate function converts a string representation of a date
or time into a broken-down time.
The external variable or macro getdate_err is used by getdate() to return
error values.
Templates are used to parse and interpret the input string. The
templates are contained in a text file 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 conversion into the internal time format.
The following field descriptors are supported:
%% 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 0 is optional)
%D date as %m/%d/%y
%e same as %d
%h abbreviated month name
%H hour (00-23)
%I hour (01-12)
Page 1
getdate(3C)getdate(3C)
%m month number (01-12)
%M minute (00-59)
%n same as new line
%p locale's equivalent of either AM or PM
%r The locale's appropriate representation of time in AM and PM
notation. In the POSIX locale, this is equivalent to %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. 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 years
in the twenty-first century (2000 to 2068 inclusive).
%Y year as ccyy (for example, 1994)
%Z time zone name or no characters if no time zone exists. If the time
zone supplied by %Z is not the time zone that getdate() expects, an
invalid input specification error will result. The getdate()
function calculates an expected time zone based on information
supplied to the function (such as the hour, day, and month).
The match between the template and input specification performed by
getdate() is case insensitive.
The month and weekday names can consist of any combination of upper and
lower case letters. The process can request that the input date or time
specification be in a specific language by setting the LC_TIME category
(see setlocale()).
Leading 0's are not necessary for the descriptors that allow leading 0's.
However, at most two digits are allowed for those descriptors, including
leading 0's. Extra whitespace in either the template file or in string
is ignored.
Page 2
getdate(3C)getdate(3C)
The field descriptors %c, %x, and %X will not be supported if they
include unsupported field descriptors.
The following rules apply for converting the input specification into the
internal format:
If %Z is being scanned, then getdate() initialises the broken-down
time to be the current time in the scanned time zone. Otherwise it
initialises the broken-down time based on the current local time as
if localtime() had been called.
If only the weekday is given, today is assumed if the given day is
equal to the current day and next week if it is less.
If only the month is given, the current month is assumed if the
given month is equal to the current month and next year if it is
less and no year is given (the first day of month is assumed if no
day is given).
If no hour, minute and second are given the current hour, minute and
second are assumed,
If no date is given, today is assumed if the given hour is greater
than the current hour and tomorrow is assumed if it is less.
If a field descriptor specification in the DATEMSK file does not
correspond to one of the field descriptors above, the behaviour is
unspecified.
RETURN VALUE
Upon successful completion, getdate() returns a pointer to a struct tm.
Otherwise, it returns a null pointer and getdate_err is set to indicate
the error.
ERRORS
The getdate() function will fail in the following cases, setting
getdate_err to the value shown in the list below. Any changes to errno
are unspecified.
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 I/O error is encountered while reading the template file.
6 Memory allocation failed (not enough memory available).
Page 3
getdate(3C)getdate(3C)
7 There is no line in the template that matches the input.
8 Invalid input specification. For 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).
EXAMPLE
Example 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
Example 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:
Page 4
getdate(3C)getdate(3C)
getdate("freitag den 10. oktober 1986 10.30 Uhr");
Example 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") %d.%m.%y
getdate("86-11-27") %y-%m-%d
getdate("Friday 12:00:00") %A %H:%M:%S
Example 4:
The following examples help to illustrate the above rules assuming that
the current date is 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 Sep 1 12:19:47 EDT 1986
January %B Thu Jan 1 12:19:47 EST 1987
December %B Mon Dec 1 12:19:47 EST 1986
Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986
Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987
Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986
Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989
Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986
Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987
10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986
13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986
APPLICATION USAGE
Although historical versions of getdate() did not require that <time.h>
declare the external variable getdate_err, this document does require it.
The Open Group encourages applications to remove declarations of
getdate_err and instead incorporate the declaration by including
<time.h>.
SEE ALSOctime(), ctype(), localtime(), setlocale(), strftime(), times(), <time.h>
Page 5
