summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/getdate.texi74
1 files changed, 66 insertions, 8 deletions
diff --git a/doc/getdate.texi b/doc/getdate.texi
index 1d312a689..9280c5087 100644
--- a/doc/getdate.texi
+++ b/doc/getdate.texi
@@ -51,11 +51,12 @@ arguments to the various programs. The C interface (via the
* General date syntax:: Common rules.
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
-* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* 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.
* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
@end menu
@@ -74,7 +75,7 @@ many flavors of items:
@itemize @bullet
@item calendar date items
-@item time of the day items
+@item time of day items
@item time zone items
@item day of the week items
@item relative items
@@ -108,7 +109,8 @@ abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
@cindex language, in dates
@cindex time zone item
-The output of @command{date} is not always acceptable as a date string,
+The output of the @command{date} command
+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,
@@ -225,7 +227,7 @@ day. Here are some examples, all of which represent the same 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
+More generally, the time of 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 possibly followed by
@@ -257,7 +259,7 @@ of zone minutes. When a time zone correction is given this way, it
forces interpretation of the time relative to
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
+part of the time of 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.
@@ -285,6 +287,10 @@ 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.
+If neither a time zone item nor a time zone correction is supplied,
+time stamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
@node Day of week items
@section Day of week items
@@ -372,7 +378,7 @@ 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 a boundary
-where the clocks were adjusted, typically for daylight-saving time,
+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
@@ -413,7 +419,7 @@ calendar date.
If the decimal number is of the form @var{hh}@var{mm} and no other time
of day item appears before it in the date string, then @var{hh} is read
as the hour of the day and @var{mm} as the minute of the hour, for the
-specified time of the day. @var{mm} can also be omitted.
+specified time of day. @var{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
@@ -427,7 +433,8 @@ 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.
+infinity. Such a number cannot be combined with any other date
+item, as it specifies a complete time stamp.
@cindex beginning of time, for @acronym{POSIX}
@cindex epoch, for @acronym{POSIX}
@@ -452,6 +459,57 @@ For example, on most systems @samp{@@915148799} represents 1998-12-31
@sc{utc}, and there is no way to represent the intervening leap second
1998-12-31 23:59:60 @sc{utc}.
+@node Specifying time zone rules
+@section Specifying time zone rules
+
+@vindex TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set. To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}. The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the @acronym{GNU} @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2004?'' by using a date beginning with
+@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
+
+@example
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+Sun Oct 31 01:30:00 EDT 2004
+@end example
+
+In this example, the @option{--date} operand begins with its own
+@env{TZ} setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
+06:30} as if it were in Paris. However, since the output of the
+@command{date} command is processed according to the overall time zone
+rules, it uses New York time. (Paris was normally six hours ahead of
+New York in 2004, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
+@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
+A recent catalog of location names appears in the
+@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
+Gateway}. A few non-@acronym{GNU} hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
+@samp{TZ=":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
+if you are at sea and have your own private time zone, or if you are
+using a non-@acronym{GNU} host that does not support the @samp{tz}
+database, you may need to use a @acronym{POSIX} rule instead. Simple
+@acronym{POSIX} rules like @samp{UTC0} specify a time zone without
+daylight saving time; other rules can specify simple daylight saving
+regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
@node Authors of get_date
@section Authors of @code{get_date}