GETDATE(3)

NAME
getdate - convert time and date from ASCII

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

time_t getdate(buf, now)
char *buf;
struct timeb *now;

DESCRIPTION
Getdate converts most common time specifications to standard UNIX internal representation. The first argument is the character string containing the time and date; the second is the assumed current time (used for relative specifications); if NULL is passed, ftime(2) is used to obtain the current time and timezone.

The character string consists of 0 or more specifications of the following form:

tod A tod is a time of day, which is of the form hh:mm[:ss] (or hhmm) [meridian] [zone]. If no meridian - am or pm - is specified, a 24-hour clock is used. A tod may be specified as just hh followed by a meridian.

date
    A date is a specific month and day, and possibly a year. Acceptable formats are mm/dd[/yy] and monthname dd[, yy] If omitted, the year defaults to the current year; if a year is specified as a number less than 100, 1900 is added. If a number not followed by a day or relative time unit occurs, it will be interpreted as a year if a tod, monthname, and dd have already been specified; otherwise, it will be treated as a tod. This rule allows the output from date(1) or ctime(3) to be passed as input to getdate.

day A day of the week may be specified; the current day will be used if appropriate. A day may be preceeded by a number, indicating which instance of that day is desired; the default is 1. Negative numbers indicate times past. Some symbolic numbers are accepted: last, next, and the ordinals first through twelfth (second is ambiguous, and is not accepted as an ordinal number). The symbolic number next is equivalent to 2; thus, next monday refers not to the immediately coming Monday, but to the one a week later.

relative time
    Specifications relative to the current time are also accepted. The format is [number] unit; acceptable units are year, month, fortnight, week, day, hour, minute, and second.

The actual date is formed as follows: first, any absolute date and/or time is processed and converted. Using that time as the base, day-of-week specifications are added; last, relative specifications are used. If a date or day is specified, and no absolute or relative time is given, midnight is used. Finally, a correction is applied so that the correct hour of the day is produced after allowing for daylight savings time differences.

Getdate accepts most common abbreviations for days, months, etc.; in particular, it will recognize them with upper or lower case first letter, and will recognize three-letter abbreviations for any of them, with or without a trailing period. Units, such as weeks, may be specified in the singular or plural. Timezone and meridian values may be in upper or lower case, and with or without periods.

SEE ALSO
ctime(3), getabsdate(3), time(2)

AUTHOR
Steven M. Bellovin (unc!smb), Dept. of Computer Science, University of North Carolina at Chapel Hill

BUGS
Because yacc(1) is used to parse the date, getdate cannot be used as a subroutine to any program that also needs yacc.
Getdate is slow; this is partly yacc's fault.
The grammar and scanner are rather primitive; certain desirable and unambiguous constructions are not accepted. Worse yet, the meaning of some legal phrases is not what is expected; next week is identical to 2 weeks.
Getdate is eager to make sense of buf, and in its zeal sometimes produces incorrect results rather than a diagnostic. Relative times are bad; all-numeric dates are worse (what does 1/12/85 mean? in the US? in Canada? in England?); a single letter is worst: it will be taken to be a US military time zone.
The daylight savings time correction is not perfect, and can get confused if handed times between midnight and 2:00 am on the days that the reckoning changes.
Because localtime(2) accepts an old-style time format without zone information, attempting to pass getdate a current time containing a different zone will probably fail.
There is no good way to restrict getdate to accept only absolute times.
Getdate's timezone tables are wrong, particularly the US military single-letter zones, which have their signs reversed. Alphabetic timezone names are obsolete.
Getdate firmly believes that years after 1999 do not exist; getdate will have to be killed by the year 2000.