NAME
parsedate - parse date specification

SYNOPSIS
#include <sys/types.h>
#include <sys/time.h>

parsedate(datestr,tm,currtm,past,error)
char *datestr;
struct tm *tm;
bool currtm, past, error;

DESCRIPTION
Parsedate parses a date string specification and fills in the
appropriate fields of the supplied tm structure (only the first
eight fields are set). The string may contain a date and/or time in
either order. The time fields may be returned containing -1 if the
time was not specified.

The boolean currtm controls whether the date is parsed relative to
the current date and time (true) or relative to the date and time
present in the tm structure (false). This allows "now" to be given
any desired meaning.

The boolean past controls whether the date is assumed to be in the
past (true) or future (false). This only affects incomplete
specifications such as Jan 1st or Thursday.

The boolean error controls whether an unrecognizable token is taken
as an error (true) or simply terminates the parse (false).

SYNTAX
The date may be specified in one of several standard syntaxes or by
using a limited range of natural language constructs.

The standard syntaxes are as follows:

Months should be either spelled out or specified numerically as
indicated above. Years may be specified in either two or four
digit style, or may be omitted. Commas, spaces, tabs and newlines
may be used interchangeably to delimit fields according to
individual taste. Case is ignored in recognizing all words. Month
and day names may be abbreviated to three characters, but other
words must be spelled out in full.

For compatibility with the ctime(3) subroutines, dates of the form

are also accepted.

Dates need not be completely specified. Many reasonable partial
constructs are accepted. The meaning of these may depend on past.
If past is true, then the date will be completed so that it is no
later than the current date (or the date already in tm ). If past
is false, then the date will be no earlier than the current date.

Next wednesday is the Wednesday after this Wednesday. Similarly,
next Christmas is the Christmas after this Christmas. Last
Thursday is the Thursday before today.

The time may be indicated in military notation, 24 hour, am/pm or
unqualified 12 hour notation. The last is taken to be a time no
earlier than 8am. Thus, 8 means 8am but 7 means 7pm. Military time
is always four digits, such as 0300. 24 hour time always has two
digits for the hour. Thus 03:00 is 3am (24 hour time) but 3:00 is
3pm (12 hour time). Natural language may also be used to qualify
the meaning of times, as in 3 in the morning.

If the time is specified but the date is not, then the current date
will be assumed.

EXAMPLES
The following examples illustrate the use of standard syntaxes and
also some of the natural language constructs.

Tue Jan 1 11:56 1980
3-December-80,14:23:00
March 4, 1984 11:01
12/22/79
12:00
today 7pm
this morning at 5
Thursday at 3
three weeks before christmas
four weeks from today
next Wednesday 17:00
10th
ten days after 25th June 03:00
friday 13th at 1530
the second friday after christmas
three days ago
a month ago
two years from today
now
11

10th means the future (or past) 10th day of some month. For
instance, if the current date is June 20, then 10th will indicate
July 10 if past is false, and June 10 if past is true. Of course,
on June 10, 10th would indicate June 10.

ten days after 25th June 03:00. Here the partial date is 25th
June. The date indicated is ten days after whatever 25th June is
taken as. On 20th June 1984, that would be 1984 or 1983 depending
on past.

a month ago means exactly one month before the current date (not 30
days ago). On 15th March 1984, that would be 15th February 1984.

now means the date and time already in the tm structure (or the
current date and time if currtm is true).

11 means 11am on the current date.

SEE ALSO
time(2), atot(3), ctime(3), gtime(3), localtime(3)

DIAGNOSTICS
Returns 0 if date is parsed successfully. Returns -1 on error with
the contents of the tm structure undefined.

BUGS
The grammar is incomplete and always will be.

The length of the date string is limited to 80 characters.

Dates before 1900 can be parsed, however the Gregorian Calendar is
always used, even for dates before it came into effect.