Date input formats
******************

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 zero A.D., computer integers are not big enough for such a (comparatively) long time.  The earliest date semantically allowed on Unix systems is midnight, 1 January 1970 UCT.

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.

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.

Calendar date item
==================

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:

     1970-09-17           # ISO 8601.
     70-9-17              # This century assumed by default.
     70-09-17             # Leading zeros are ignored.
     9/17/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/17
     sep 17

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 less than 100, then 1900 is added to it to force a date in this century.  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

Time of day item
================

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 (Eastern U.S. 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.

The time may alternatively be followed by a timezone 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 timezone correction is given this way, it forces interpretation of the time in UTC, overriding any previous specification for the timezone or the local timezone.  The MINUTE part of the time of the day may not be elided when a timezone correction is used.  This is the only way to specify a timezone correction by fractional parts of an hour.

Either am/pm or a timezone correction may be specified, but not both.

Timezone item
=============

A timezone item specifies an international timezone, indicated by a small set of letters.  Any included period is ignored.  Military timezone designations use a single letter.  Currently, only integral zone hours may be represented in a timezone item.  See the previous section for a finer control over the timezone correction.

Here are many non-daylight-savings-time timezones, indexed by the zone hour value.

+000
     GMT for Greenwich Mean, UT or UTC for Universal (Coordinated), WET for Western European and Z for militaries.

+100
     WAT for West Africa and A for militaries.

+200
     AT for Azores and B for militaries.

+300
     C for militaries.

+400
     AST for Atlantic Standard and D for militaries.

+500
     E for militaries and EST for Eastern Standard.

+600
     CST for Central Standard and F for militaries.

+700
     G for militaries and MST for Mountain Standard.

+800
     H for militaries and PST for Pacific Standard.

+900
     I for militaries and YST for Yukon Standard.

+1000
     AHST for Alaska-Hawaii Standard, CAT for Central Alaska, HST for Hawaii Standard and K for militaries.

+1100
     L for militaries and NT for Nome.

+1200
     IDLW for International Date Line West and M for militaries.

-100
     CET for Central European, FWT for French Winter, MET for Middle European, MEWT for Middle European Winter, N for militaries and SWT for Swedish Winter.

-200
     EET for Eastern European, USSR Zone 1 and O for militaries.

-300
     BT for Baghdad, USSR Zone 2 and P for militaries.

-400
     Q for militaries and ZP4 for USSR Zone 3.

-500
     R for militaries and ZP5 for USSR Zone 4.

-600
     S for militaries and ZP6 for USSR Zone 5.

-700
     T for militaries and WAST for West Australian Standard.

-800
     CCT for China Coast, USSR Zone 7 and U for militaries.

-900
     JST for Japan Standard, USSR Zone 8 and V for militaries.

-1000
     EAST for East Australian Standard, GST for Guam Standard, USSR Zone 9 and W for militaries.

-1100
     X for militaries.

-1200
     IDLE for International Date Line East, NZST for New Zealand Standard, NZT for New Zealand and Y for militaries.

Here are many DST timezones, indexed by the zone hour value.  Also, by following a non-DST timezone by the string DST in a separate word (that is, separated by some whitespace), the corresponding DST timezone may be specified.

0
     BST for British Summer.

+400
     ADT for Atlantic Daylight.

+500
     EDT for Eastern Daylight.

+600
     CDT for Central Daylight.

+700
     MDT for Mountain Daylight.

+800
     PDT for Pacific Daylight.

+900
     YDT for Yukon Daylight.

+1000
     HDT for Hawaii Daylight.

-100
     MEST for Middle European Summer, MESZ for Middle European Summer, SST for Swedish Summer and FST for French Summer.

-700
     WADT for West Australian Daylight.

-1000
     EADT for Eastern Australian Daylight.

-1200
     NZDT for New Zealand Daylight.

Day of week item
================

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.

Relative item 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 multiplicator 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 change 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 makes the resulting date to cross the boundary between DST and non-DST (or vice-versa), the hour is adjusted according to the local time.

Pure numbers in date strings
============================

The precise intepretation of a pure decimal number is dependent of the context in the date string.

If the decimal number is of the form YYYYMMDD and no other calendar date item (see Calendar date item) 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.

Authors of getdate
==================

getdate was originally implemented by Steven M. Bellovin (smb@research.att.com) 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 (rsalz@bbn.com) and Jim Berets (jberets@bbn.com) in August, 1990.  Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, and others.

This chapter was originally produced by Franc,ois Pinard (pinard@iro.umontreal.ca) from the getdate.y source code, and then edited by K. Berry (kb@cs.umb.edu).