X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Fgetdate.texi;h=30d4d33727b51b3ff0349afbe97db5fc6abcf499;hb=d4bcefe915fc07ef18615586ab247388582fb45a;hp=78522b2ac5abc90a396fee49a7bdd15229177f40;hpb=addd73b34a6d592c19cc6b27203a235b385b8a54;p=chaz%2Ftar diff --git a/doc/getdate.texi b/doc/getdate.texi index 78522b2..30d4d33 100644 --- a/doc/getdate.texi +++ b/doc/getdate.texi @@ -1,6 +1,17 @@ @node Date input formats @chapter Date input formats +@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2003 Free Software +@c 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 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, with no +@c Front-Cover Texts, and with no Back-Cover Texts. +@c A copy of the license is included in the section entitled ``GNU +@c Free Documentation License''. + @cindex date input formats @findex getdate @@ -30,27 +41,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 @acronym{POSIX} +@cindex epoch, for @acronym{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 @acronym{POSIX} systems, the clock starts at 1970-01-01 00:00:00 +@sc{utc}: @acronym{POSIX} does not require support for times before the +@acronym{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 known +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, Salz, Berets, et al. @end menu @@ -95,6 +111,34 @@ 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. +@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 +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 +@end example + @cindex case, ignored in dates @cindex comments, in dates Alphabetic case is completely ignored in dates. Comments may be introduced @@ -113,7 +157,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 +180,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 +230,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 +250,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 +261,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 +276,20 @@ 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. - -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 @@ -409,7 +357,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 +377,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,8 +387,8 @@ to the local time. @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 @@ -468,13 +416,14 @@ year. @cindex Berets, Jim @cindex MacKenzie, David @cindex Meyering, Jim +@cindex Eggert, Paul @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, +Paul Eggert and others. @cindex Pinard, F. @cindex Berry, K.