+@c GNU date syntax documentation
+
+@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
+@c 2003, 2004 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.1 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+@c Texts. A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
@node Date input formats
@chapter Date input formats
@cindex date input formats
-@findex getdate
+@findex get_date
First, a quote:
--- Robert Grudin, @cite{Time and the Art of Living}.
@end quotation
-This section describes the textual date representations that GNU
+This section describes the textual date representations that @sc{gnu}
programs accept. These are the strings you, as a user, can supply as
arguments to the various programs. The C interface (via the
-@code{getdate} function) is not described here.
-
-@cindex beginning of time, for Unix
-@cindex epoch, for Unix
-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.
+@code{get_date} function) is not described here.
@menu
* General date syntax:: Common rules.
-* Calendar date items:: 19 Dec 1994.
-* Time of day items:: 9:20pm.
-* Time zone items:: EST, DST, BST, UTC, ...
-* Day of week items:: Monday and others.
-* Relative items in date strings:: next tuesday, 2 years ago.
+* Calendar date items:: 19 Dec 1994.
+* Time of day items:: 9:20pm.
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* Day of week items:: Monday and others.
+* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
-* Authors of getdate:: Bellovin, Salz, Berets, et al.
+* Seconds since the Epoch:: @@1078100502.
+* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
@end menu
numerically, instead of being ``spelled in full''; this changes the
allowed strings.
+@cindex language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
+@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
+@cindex language, in dates
+@cindex time zone item
+The output of @command{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 @samp{IST}. When using
+@command{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 @samp{UTC} and @samp{Z}. Here are some
+ways to do this:
+
+@example
+$ LC_ALL=C TZ=UTC0 date
+Mon Mar 1 00:21:42 UTC 2004
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2004-03-01 00:21:42Z
+$ date --iso-8601=ns # a GNU extension
+2004-02-29T16:21:42,692722128-0800
+$ date --rfc-2822 # a GNU extension
+Sun, 29 Feb 2004 16:21:42 -0800
+$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
+2004-02-29 16:21:42 -0800
+$ date +'@@%s.%N' # %s and %N are GNU extensions.
+@@1078100502.692722128
+@end example
+
@cindex case, ignored in dates
@cindex comments, in dates
Alphabetic case is completely ignored in dates. Comments may be introduced
numerically or literally. All these strings specify the same calendar date:
@example
-1972-09-24 # ISO 8601.
+1972-09-24 # @sc{iso} 8601.
72-9-24 # Assume 19xx for 69 through 99,
# 20xx for 00 through 68.
72-09-24 # Leading zeros are ignored.
Here are the rules.
-@cindex ISO 8601 date format
-@cindex date format, ISO 8601
-For numeric months, the ISO 8601 format
+@cindex @sc{iso} 8601 date format
+@cindex date format, @sc{iso} 8601
+For numeric months, the @sc{iso} 8601 format
@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
any positive number, @var{month} is a number between 01 and 12, and
@var{day} is a number between 01 and 31. A leading zero must be present
day. Here are some examples, all of which represent the same time:
@example
-20:02:0
+20:02:00.000000
20:02
8:02pm
-20:02-0500 # In EST (Eastern U.S. Standard Time).
+20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
@end example
More generally, the time of the day may be given as
@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
a number between 0 and 23, @var{minute} is a number between 0 and
-59, and @var{second} is a number between 0 and 59. Alternatively,
+59, and @var{second} is a number between 0 and 59 possibly followed by
+@samp{.} or @samp{,} and a fraction containing one or more digits.
+Alternatively,
@samp{:@var{second}} can be omitted, in which case it is taken to
be zero.
indicates the first half of the day, @samp{pm} indicates the second
half of the day. In this notation, 12 is the predecessor of 1:
midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
@cindex time zone correction
@cindex minutes, time zone correction by
or @samp{-}, @var{hh} is a number of zone hours and @var{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
+Coordinated Universal Time (@sc{utc}), overriding any previous
specification for the time zone or the local time zone. The @var{minute}
part of the time of the day may not be elided when a time zone correction
-is used. This is the only way to specify a time zone correction by
+is used. This is the best way to specify a time zone correction by
fractional parts of an hour.
Either @samp{am}/@samp{pm} or a time zone correction may be specified,
@cindex time zone item
-A @dfn{time zone item} specifies an international time zone, indicated by
-a small set of letters. They are supported for backward compatibility reasons,
-but they are not recommended because they are ambiguous in practice:
-for example, the abbreviation @samp{EST} has different meanings in
-Australia and the United States. Any included period is ignored. Military
-time zone designations use a single letter. Currently, only integral
-zone hours may be represented in a time zone item. See the previous
-section for a finer control over the time zone correction.
-
-Here are many non-daylight-saving-time time zones, indexed by the zone
-hour value.
-
-@table @asis
-@item -1200
-@samp{Y} for militaries.
-@item -1100
-@samp{X} for militaries.
-@item -1000
-@samp{W} for militaries.
-@item -0900
-@samp{V} for militaries.
-@item -0800
-@samp{PST} for Pacific Standard, and
-@samp{U} for militaries.
-@item -0700
-@samp{MST} for Mountain Standard, and
-@samp{T} for militaries.
-@item -0600
-@samp{CST} for Central Standard, and
-@samp{S} for militaries.
-@item -0500
-@samp{EST} for Eastern Standard, and
-@samp{R} for militaries.
-@item -0400
-@samp{AST} for Atlantic Standard, and
-@samp{Q} for militaries.
-@item -0300
-@samp{P} for militaries.
-@item -0200
-@samp{O} for militaries.
-@item -0100
-@samp{N} for militaries.
-@item +0000
-@cindex Greenwich Mean Time
-@cindex Coordinated Universal Time
-@cindex Universal Coordinated Time
-@cindex Universal Time (Coordinated)
-@samp{GMT} for Greenwich Mean,
-@samp{UT} for Universal,
-@samp{UTC} for Coordinated Universal,
-@samp{WET} for Western European, and
-@samp{Z} for ISO 8601 and militaries.
-@item +0100
-@samp{A} for militaries,
-@samp{CET} for Central European,
-@samp{MET} for Midden Europesche Tijd (Dutch), and
-@samp{MEZ} for Mittel-Europ@"aische Zeit (German).
-@item +0200
-@samp{B} for militaries, and
-@samp{EET} for Eastern European.
-@item +0300
-@samp{C} for militaries.
-@item +0400
-@samp{D} for militaries.
-@item +0500
-@samp{E} for militaries.
-@item +0600
-@samp{F} for militaries.
-@item +0700
-@samp{G} for militaries.
-@item +0800
-@samp{H} for militaries.
-@item +0900
-@samp{I} for militaries, and
-@samp{JST} for Japan Standard.
-@item +1000
-@samp{GST} for Guam Standard, and
-@samp{K} for militaries.
-@item +1100
-@samp{L} for militaries.
-@item +1200
-@samp{M} for militaries, and
-@samp{NZST} for New Zealand Standard.
-@end table
-
-@cindex daylight-saving time
-Here are many daylight-saving time (DST) time zones,
-indexed by the zone hour value. Also, by
-following a non-DST time zone by the string @samp{DST} in a separate word
-(that is, separated by some whitespace), the corresponding DST time zone
-may be specified.
-
-@table @asis
-@item -0700
-@samp{PDT} for Pacific Daylight.
-@item -0600
-@samp{MDT} for Mountain Daylight.
-@item -0500
-@samp{CDT} for Central Daylight.
-@item -0400
-@samp{EDT} for Eastern Daylight.
-@item -0300
-@samp{ADT} for Atlantic Daylight.
-@item +0100
-@samp{BST} for British Summer, and
-@samp{WEST} for Western European Summer.
-@item +0200
-@samp{CEST} for Central European Summer,
-@samp{MEST} for Midden Europesche S. Tijd (Dutch), and
-@samp{MESZ} for Mittel-Europ@"aische Sommerzeit (German).
-@item +1300
-@samp{NZDT} for New Zealand Daylight.
-@end table
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time. Any included periods are ignored. By following a
+non-daylight-saving time zone by the string @samp{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 @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States. Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
@node Day of week items
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 @samp{ago} is equivalent to preceding the unit by a
-multiplicator with value @math{-1}.
+multiplier with value @math{-1}.
@findex day @r{in date strings}
@findex tomorrow @r{in date strings}
the meaning of a zero-valued time displacement, but is preferred in
date strings like @samp{this thursday}.
-When a relative item causes the resulting date to cross the boundary
-between DST and non-DST (or vice-versa), the hour is adjusted according
-to the local time.
+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.
+
+The fuzz in units can cause problems with relative items. For
+example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
+because 2003-06-31 is an invalid date. To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month. For example:
+
+@example
+$ date -R
+Thu, 31 Jul 2003 13:02:39 -0700
+$ date --date='-1 month' +'Last month was %B?'
+Last month was July?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was June!
+@end example
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
+@samp{UTC0} before embarking on calendrical calculations.
@node Pure numbers in date strings
@section Pure numbers in date strings
@cindex pure numbers in date strings
-The precise intepretation of a pure decimal number depends
-the context in the date string.
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
other calendar date item (@pxref{Calendar date items}) appears before it
year.
-@node Authors of getdate
-@section Authors of @code{getdate}
+@node Seconds since the Epoch
+@section Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal time
+stamp as a count of seconds. The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity.
+
+@cindex beginning of time, for @acronym{POSIX}
+@cindex epoch, for @acronym{POSIX}
+Internally, computer times are represented as a count of seconds since
+an epoch---a well-defined point of time. On @acronym{GNU} and
+@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
+@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
+@acronym{POSIX}-compliant systems support such times as an extension
+to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 @sc{utc}.
+
+Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
+of seconds with nanosecond subcounts, and can represent all the times
+in the known lifetime of the universe to a resolution of 1 nanosecond.
+
+On most systems, these counts ignore the presence of leap seconds.
+For example, on most systems @samp{@@915148799} represents 1998-12-31
+23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
+@sc{utc}, and there is no way to represent the intervening leap second
+1998-12-31 23:59:60 @sc{utc}.
+
+@node Authors of get_date
+@section Authors of @code{get_date}
-@cindex authors of @code{getdate}
+@cindex authors of @code{get_date}
@cindex Bellovin, Steven M.
@cindex Salz, Rich
@cindex Berets, Jim
@cindex MacKenzie, David
@cindex Meyering, Jim
-@code{getdate} was originally implemented by Steven M. Bellovin
+@cindex Eggert, Paul
+@code{get_date} was originally implemented by Steven M. Bellovin
(@email{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 (@email{rsalz@@bbn.com})
and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
-revisions for the GNU system were made by David MacKenzie, Jim Meyering,
-and others.
+revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others.
@cindex Pinard, F.
@cindex Berry, K.
projects / chaz / tar / blobdiff