4. Date input formats

First, a quote:

Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time.

... It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. ...

--- Robert Grudin, Time and the Art of Living.

This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the getdate function) is not described here.

Although the date syntax here can represent any possible time since the year zero, computer integers often cannot represent such a wide range of time. On POSIX systems, the clock starts at 1970-01-01 00:00:00 UTC: POSIX does not require support for times before the POSIX Epoch and times far in the future. Traditional Unix systems have 32-bit signed time_t and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. Systems with 64-bit signed time_t can represent all the times in the known lifetime of the universe.

4.1 General date syntax		Common rules.
4.2 Calendar date items		19 Dec 1994.
4.3 Time of day items		9:20pm.
4.4 Time zone items		EST, PDT, GMT, ...
4.5 Day of week items		Monday and others.
4.6 Relative items in date strings		next tuesday, 2 years ago.
4.7 Pure numbers in date strings		19931219, 1440.
4.8 Authors of getdate		Bellovin, Eggert, Salz, Berets, et al.

4.1 General date syntax

A date is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items:

• calendar date items
• time of the day items
• time zone items
• day of the week items
• relative items
• pure numbers.

We describe each of these item types in turn, below.

A few numbers may be written out in words in most contexts. This is most useful for specifying day of the week items or relative items (see below). Here is the list: `first' for 1, `next' for 2, `third' for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6, `seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10, `eleventh' for 11 and `twelfth' for 12. Also, `last' means exactly -1.

When a month is written this way, it is still considered to be written numerically, instead of being "spelled in full"; this changes the allowed strings.

In the current implementation, only English is supported for words and abbreviations like `AM', `DST', `EST', `first', `January', `Sunday', `tomorrow', and `year'.

The output of date is not always acceptable as a date string, not only because of the language problem, but also because there is no standard meaning for time zone items like `IST'. When using date to generate a date string intended to be parsed later, specify a date format that is independent of language and that does not use time zone items other than `UTC' and `Z'. Here are some ways to do this:

$ LC_ALL=C TZ=UTC0 date Fri Dec 15 19:48:05 UTC 2000 $ TZ=UTC0 date +"%Y-%m-%d %H:%M:%SZ" 2000-12-15 19:48:05Z $ date --iso-8601=seconds # a GNU extension 2000-12-15T11:48:05-0800 $ date --rfc-822 # a GNU extension Fri, 15 Dec 2000 11:48:05 -0800 $ date +"%Y-%m-%d %H:%M:%S %z" # %z is a GNU extension. 2000-12-15 11:48:05 -0800

Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored.

4.2 Calendar date items

A calendar date item specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date:

1972-09-24 # ISO 8601. 72-9-24 # Assume 19xx for 69 through 99, # 20xx for 00 through 68. 72-09-24 # Leading zeros are ignored. 9/24/72 # Common U.S. writing. 24 September 1972 24 Sept 72 # September has a special abbreviation. 24 Sep 72 # Three-letter abbreviations always allowed. Sep 24, 1972 24-sep-72 24sep72

The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example:

9/24 sep 24

Here are the rules.

For numeric months, the ISO 8601 format `year-month-day' is allowed, where year is any positive number, month is a number between 01 and 12, and day is a number between 01 and 31. A leading zero must be present if a number is less than ten. If year is 68 or smaller, then 2000 is added to it; otherwise, if year is less than 100, then 1900 is added to it. The construct `month/day/year', popular in the United States, is accepted. Also `month/day', omitting the year.

Literal months may be spelled out in full: `January', `February', `March', `April', `May', `June', `July', `August', `September', `October', `November' or `December'. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write `Sept' instead of `September'.

When months are written literally, the calendar date may be given as any of the following:

day month year day month month day year day-month-year

Or, omitting the year:

month day

4.3 Time of day items

A time of day item in date strings specifies the time on a given day. Here are some examples, all of which represent the same time:

20:02:0 20:02 8:02pm 20:02-0500 # In EST (U.S. Eastern Standard Time).

More generally, the time of the day may be given as `hour:minute:second', where hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59. Alternatively, `:second' can be omitted, in which case it is taken to be zero.

If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), hour is restricted to run from 1 to 12, and `:minute' may be omitted (taken to be zero). `am' indicates the first half of the day, `pm' indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is `12am' while noon is `12pm'. (This is the zero-oriented interpretation of `12am' and `12pm', as opposed to the old tradition derived from Latin which uses `12m' for noon and `12pm' for midnight.)

The time may alternatively be followed by a time zone correction, expressed as `shhmm', where s is `+' or `-', hh is a number of zone hours and mm is a number of zone minutes. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. The minute part of the time of the day may not be elided when a time zone correction is used. This is the best way to specify a time zone correction by fractional parts of an hour.

Either `am'/`pm' or a time zone correction may be specified, but not both.

4.4 Time zone items

A time zone item specifies an international time zone, indicated by a small set of letters, e.g., `UTC' or `Z' for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string `DST' in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified.

Time zone items other than `UTC' and `Z' are obsolescent and are not recommended, because they are ambiguous; for example, `EST' has a different meaning in Australia than in the United States. Instead, it's better to use unambiguous numeric time zone corrections like `-0500', as described in the previous section.

4.5 Day of week items

The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future.

Days of the week may be spelled out in full: `Sunday', `Monday', `Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations `Tues' for `Tuesday', `Wednes' for `Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like `third monday'. In this context, `last day' or `next day' is also acceptable; they move one week before or after the day that day by itself would represent.

A comma following a day of the week item is ignored.

4.6 Relative items in date strings

Relative items adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples:

1 year 1 year ago 3 years 2 days

The unit of time displacement may be selected by the string `year' or `month' for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are `fortnight' which is worth 14 days, `week' worth 7 days, `day' worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60 seconds, and `second' or `sec' worth one second. An `s' suffix on these units is accepted and ignored.

The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string `ago' is equivalent to preceding the unit by a multiplier with value -1.

The string `tomorrow' is worth one day in the future (equivalent to `day'), the string `yesterday' is worth one day in the past (equivalent to `day ago').

The strings `now' or `today' are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in `12:00 today'. The string `this' also has the meaning of a zero-valued time displacement, but is preferred in date strings like `this thursday'.

When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight-saving time, the resulting date and time are adjusted accordingly.

4.7 Pure numbers in date strings

The precise interpretation of a pure decimal number depends on the context in the date string.

If the decimal number is of the form yyyymmdd and no other calendar date item (see section 4.2 Calendar date items) appears before it in the date string, then yyyy is read as the year, mm as the month number and dd as the day of the month, for the specified calendar date.

If the decimal number is of the form hhmm and no other time of day item appears before it in the date string, then hh is read as the hour of the day and mm as the minute of the hour, for the specified time of the day. mm can also be omitted.

If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year.

4.8 Authors of getdate

getdate was originally implemented by Steven M. Bellovin ([email protected]) while at the University of North Carolina at Chapel Hill. The code was later tweaked by a couple of people on Usenet, then completely overhauled by Rich $alz ([email protected]) and Jim Berets ([email protected]) in August, 1990. Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert and others.

This chapter was originally produced by François Pinard ([email protected]) from the `getdate.y' source code, and then edited by K. Berry ([email protected]).