NAME
getdate,
getdate_err —
convert user format date and time
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <time.h>
struct tm *
getdate(
const char *str);
extern int getdate_err;
DESCRIPTION
The
getdate() function converts a date or time character
string pointed to by
str into a static
tm structure described in
tm(3).
The input string is parsed and interpreted using templates. A text file
containing templates is specified by the environment variable
DATEMSK
. This should contain the full path to the
template file. Lines in the template file represent acceptable date and/or
time conversion specifications. These specifications are similar to those
given for
strptime(3). The
first line in the template file that matches the input string is used to
interpret and convert to internal time format.
The following rules apply to converting the input into the internal format.
- If only the weekday is given, the conversion assumes
today when the weekday matches today or the first future matching
weekday.
- If only the month and no year is given, the conversion
assumes the current month when the month matches or the first future
matching month. The first day of the month is assumed if no day is
given.
- If only the year is given, the values of the
tm_mon, tm_mday,
tm_wday, tm_yday, and
tm_isdst members of the returned
struct tm are unspecified.
- If the century is given, but the year within the century
is not given, the conversion assumes the current year.
- If no hour, minute, and second are given, the conversion
assumes the current hour, minute, and second.
- If no date is given, the conversion assumes today when
the given hour is greater than the current hour and tomorrow when the
given hour is less.
- If %Z is being scanned, then the
broken-down time is based on the the current time of the matched timezone
and not the current runtime environment timezone.
RETURN VALUES
If successful, the
getdate() function returns a pointer to a
static
tm structure containing the broken-down time.
Otherwise, a null pointer is returned and
getdate_err is
set to indicate the error.
The variable
getdate_err can have the following values:
-
-
- 1
DATEMSK
environment variable is
null or undefined.
-
-
- 2
- Cannot open the template file for reading.
-
-
- 3
- Get file status failed for template file.
-
-
- 4
- Template file is not a regular file.
-
-
- 5
- Encountered an error while reading the template file.
-
-
- 6
- Cannot allocate memory.
-
-
- 7
- Input string does not match any line in the template
file.
-
-
- 8
- Input string is invalid (for example, February 31) or could
not be represented in a time_t.
ENVIRONMENT
-
-
DATEMSK
- The full path to the text file containing the templates for
acceptable date and/or time conversions.
FILES
-
-
- /usr/share/examples/getdate/datemsk.template
- An example template file that could be specified via the
DATEMSK
environment variable.
EXAMPLES
The following example shows the possible contents of a template file:
%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
The following are examples of valid input for the above template:
10/1/87 4 PM
Friday
Friday September 18, 1987, 10:30:30
24,9,1986 10:30
at monday the 1st of december in 1986
run job at 3 PM, december 2nd
The following examples show how local data and time specification can be defined
in the template.
Input String |
Line in Template |
11/27/86 |
%m/%d/%y |
27.11.86 |
%d.%m.%y |
86-11-27 |
%y-%m-%d |
Friday 12:00:00 |
%A %H:%M:%S |
The following examples illustrate the Internal Format Conversion rules given
that the current date is
Mon Sep 22 12:19:47 EDT 1986
and the
LC_TIME
environment variable is set to the
default C locale.
Input String |
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 |
Tue Sep 22 13:30:00 EDT
1986 |
SEE ALSO
ctime(3),
localtime(3),
mktime(3),
strftime(3),
strptime(3),
time(3)
STANDARDS
The
getdate() function conforms to
IEEE Std
1003.1-2001 (“POSIX.1”).
HISTORY
The
getdate function appeared in
AT&T
System V Release 4 UNIX.
BUGS
The
getdate interface is inherently unsafe for multi-threaded
programs or libraries, since it returns a pointer to a static variable and
uses a global state variable.