'\"!  tbl | mmdoc
'\"macro stdmacro
.if n .pH g3c.getdate @(#)getdate	@(#)getdate	40.8 of 10/25/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getdate 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} getdate 3C "C Programming Language Utilities"
.if \nX=2 .ds x} getdate 3C "" "\&"
.if \nX=3 .ds x} getdate "" "" "\&"
.TH \*(x}
.SH NAME
\f4getdate\f1 \- convert user format date and time
.SH SYNOPSIS
.nf
.B
.PP
\f4#include <time.h>\f1
.PP
\f4struct tm \(**getdate (const char \(**string);\f1
.PP
\f4extern int getdate_err;\f1
.SH DESCRIPTION
\f4getdate\fP
converts user-definable date and/or time
specifications
pointed to by
.I string
into a
\f4tm\fP
structure.
The structure declaration is in the
\f4time.h\fP
header file [see also
\f4ctime\fP(3C)].
.PP
User-supplied templates are used to parse and
interpret the input string.  The templates are 
text files created by the user
and identified via the environment variable
\f4DATEMSK\f1.
Each line in the template represents an acceptable
date and/or time specification using some of the
same field descriptors as the ones used by the
\f4date\fP command.
The first line in the template that
matches the input specification is used for
interpretation and conversion into 
the internal time format.
If successful, the function 
\f4getdate\fP
returns a pointer to a
\f4tm\fP
structure; otherwise, it
returns \f4NULL\fP and sets the global variable
\f4getdate_err\fP
to indicate the error.
.PP
The following field descriptors are supported:
.PP
.RS
.PD 0
.TP 5
\f4%%\^\f1
same as \f4%\fP
.TP 5
\f4%a\f1
abbreviated weekday name
.TP 5
\f4%A\f1
full weekday name
.TP 5
\f4%b\f1
abbreviated month name
.TP 5
\f4%B\f1
full month name
.TP 5
\f4%c\^\f1
locale's appropriate date and time representation
.TP 5
\f4%d\f1
day of month (01-31; the leading 0 is optional)
.TP 5
\f4%e\f1
same as \f4%d\fP
.TP 5
\f4%D\^\f1
date as \f4%m/%d/%y\fP
.TP 5
\f4%h\f1
abbreviated month name
.TP 5
\f4%H\f1
hour (00-23)
.TP 5
\f4%I\f1
hour (01-12)
.TP 5
\f4%m\f1
month number (01-12)
.TP 5
\f4%M\f1
minute (00-59)
.TP 5
\f4%n\^\f1
same as \f4\en\f1
.TP 5
\f4%p\^\f1
locale's equivalent of either \s-1AM\s+1 or \s-1PM\s+1
.TP 5
\f4%r\^\f1
time as \f4%I:%M:%S %p\fP
.TP 5
\f4%R\^\f1
time as \f4%H:%M\fP
.TP 5
\f4%S\f1
seconds (00-59)
.TP 5
\f4%t\^\f1
insert a tab
.TP 5
\f4%T\^\f1
time as \f4%H:%M:%S\fP
.TP 5
\f4%w\^\f1
weekday number (0-6; Sunday = 0)
.TP 5
\f4%x\^\f1
locale's appropriate date representation
.TP 5
\f4%X\^\f1
locale's appropriate time representation
.TP 5
\f4%y\f1
year with century (00-99)
.TP 5
\f4%Y\f1
year as \f4ccyy\f1 (e.g., 1986)
.TP 5
\f4%Z\f1
time zone name or no characters if no time zone exists
.RE
.PD
.PP
The month and weekday names can consist of any combination
of upper and lower case letters.
The user can request that the input date or time specification 
be in a specific language by setting the categories
\f4LC_TIME\f1 and \f4LC_CTYPE\f1 of \f4setlocale\f1.
.PP
The following example shows the possible contents of a template:
.PP
.RS
.nf
.ft 4
%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
.ft 1
.fi
.RE
.PP
The following are examples of valid input specifications for
the above template:
.PP
.RS
.nf
.ft 4
getdate("10/1/87 4 PM")
getdate("Friday")
getdate("Friday September 19 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")
.ft 1
.fi
.RE
.PP
If the
\f4LANG\f1
environment variable is set to 
\f4german\fP,
the following is valid:
.PP
.RS
.nf
.ft 4
getdate("freitag den 10. oktober 1986 10.30 Uhr")
.ft 1
.fi
.RE
.PP
Local time and date specification are also supported.
The following
examples show how local date and time specification
can be defined in the template.
.TS
box,center;
c|c
lf4|lf4.
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
.TE
.PP
The following rules are applied for converting
the input specification into the internal format:
.IP ""
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.
.IP ""
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.)
.IP ""
If no hour, minute, and second are given, the current
hour, minute, and second are assumed.
.IP ""
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.
.PP
The following examples illustrate the above rules.
Assume that the current date is
Mon Sep 22 12:19:47 \s-1EDT\s+1 1986
and the
\f4LANG\f1
environment variable is not set. 
.TS
box,center;
c  |c  |c
lf4|lf4|l.
Input	Line in Template	Date
_
Mon	%a	Mon Sep 22 12:19:48 \s-1EDT\s+1 1986
Sun	%a	Sun Sep 28 12:19:49 \s-1EDT\s+1 1986
Fri	%a	Fri Sep 26 12:19:49 \s-1EDT\s+1 1986
September	%B	Mon Sep  1 12:19:49 \s-1EDT\s+1 1986
January	%B	Thu Jan  1 12:19:49 \s-1EST\s+1 1987
December	%B	Mon Dec  1 12:19:49 \s-1EST\s+1 1986
Sep Mon	%b %a	Mon Sep  1 12:19:50 \s-1EDT\s+1 1986
Jan Fri	%b %a	Fri Jan  2 12:19:50 \s-1EST\s+1 1987
Dec Mon	%b %a	Mon Dec  1 12:19:50 \s-1EST\s+1 1986
Jan Wed 1989	%b %a %Y	Wed Jan  4 12:19:51 \s-1EST\s+1 1989
Fri 9	%a %H	Fri Sep 26 09:00:00 \s-1EDT\s+1 1986
Feb 10:30	%b %H:%S	Sun Feb  1 10:00:30 \s-1EST\s+1 1987
10:30	%H:%M	Tue Sep 23 10:30:00 \s-1EDT\s+1 1986
13:30	%H:%M	Mon Sep 22 13:30:00 \s-1EDT\s+1 1986
.TE
.SH FILES
.ta 2.5i
\f4/usr/lib/locale/<locale>/LC_TIME\fP	language specific printable files
.br
\f4/usr/lib/locale/<locale>/LC_CTYPE\fP	code set specific printable files
.DT
.SH "SEE ALSO"
\f4setlocale\fP(3C), \f4ctype\fP(3C), \f4environ\fP(5).
.SH DIAGNOSTICS
On failure
\f4getdate\fP
returns \f4NULL\fP and sets
the variable
\f4getdate_err\fP
to indicate the error.
.PP
The following is a complete list of the 
\f4getdate_err\fP
settings and their meanings.
.RS 3
.TP 5
\f4\&1\fP
The
\f4DATEMSK\f1
environment variable is null or undefined.
.TP 5
\f4\&2\fP
The template file cannot be opened for reading.
.TP 5
\f4\&3\fP
Failed to get file status information.
.TP 5
\f4\&4\fP
The template file is not a regular file.
.TP 5
\f4\&5\fP
An error is encountered while reading the template file.
.TP 5
\f4\&6\fP
\f4malloc\fP
failed (not enough memory is available).
.TP 5
\f4\&7\fP
There is no line in the template that matches the input.
.TP 5
\f4\&8\fP
The input specification is invalid (e.g., \f4February 31\fP).
.RE
.bp
.SH NOTES
Subsequent calls to
\f4getdate\fP
alter the contents of
\f4getdate_err\fP.
.P
Dates before 1970 and after 2037 are illegal.
.P
\f4getdate\fP
makes explicit use of macros described in
\f4ctype\fP(3C).
.Ee
