mirrors/tar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

New file, taken from fileutils 4.0.27, with the

Browse Source 
following changes: Use @sc where appropriate.  Document the ranges of
supported times more precisely.  Add Eggert to getdate authors.
Document old Latin 12m/12pm tradition.  Remove list of alphabetic time
zone names, as it wasn't correct and people shouldn't be relying on it
anyway.  Relative items also account for non-DST adjustments.  Fix
some misspellings.
This commit is contained in:
Paul Eggert
2000-10-24 06:18:37 +00:00
parent e7d0a7724b
commit f566b8f147
1 changed files with 49 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
doc/getdate.texi
View File

@@ -30,27 +30,32 @@ or a week from Sunday, with feelings of helpless confusion. @dots{}
--- 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.
@cindex beginning of time, for @sc{posix}
@cindex epoch, for @sc{posix}
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 @sc{posix} systems, the clock starts at 1970-01-01 00:00:00
@sc{utc}: @sc{posix} does not require support for times before the
@sc{posix} Epoch and times far in the future. Traditional Unix systems
have 32-bit signed @code{time_t} and can represent times from 1901-12-13
20:45:52 through 2038-01-19 03:14:07 @sc{utc}. Systems with 64-bit
signed @code{time_t} can represent all the times in the expected
lifetime of the universe.
@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.
* Authors of getdate:: Bellovin, Eggert, Berets, Salz, et al.
@end menu
@@ -113,7 +118,7 @@ specified differently, depending on whether the month is specified
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.
@@ -136,9 +141,9 @@ sep 24
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
@@ -186,7 +191,7 @@ 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).
20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
@end example
More generally, the time of the day may be given as
@@ -206,6 +211,9 @@ or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
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
@@ -214,10 +222,10 @@ expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
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,
@@ -229,119 +237,18 @@ but not both.
@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.
A @dfn{time zone item} specifies an international time zone, indicated
by a small set of letters, e.g., @samp{UTC} 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.
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
Time zone items 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
@@ -409,7 +316,7 @@ 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 @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}
@@ -429,9 +336,9 @@ items, like in @samp{12:00 today}. The string @samp{this} also has
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.
@node Pure numbers in date strings
@@ -439,7 +346,7 @@ to the local time.
@cindex pure numbers in date strings
The precise intepretation of a pure decimal number depends
The precise interpretation of a pure decimal number depends
the context in the date string.
If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
@@ -464,17 +371,19 @@ year.
@cindex authors of @code{getdate}
@cindex Bellovin, Steven M.
@cindex Salz, Rich
@cindex Berets, Jim
@cindex Eggert, Paul
@cindex MacKenzie, David
@cindex Meyering, Jim
@cindex Salz, Rich
@code{getdate} 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,
and others. The code was rewritten again in 1999 by Paul Eggert,
to improve its support for daylight saving time.
@cindex Pinard, F.
@cindex Berry, K.