@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
arguments to the various programs. The C interface (via the
@code{getdate} function) is not described here.
-@cindex beginning of time, for @sc{posix}
-@cindex epoch, for @sc{posix}
+@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 @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
+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
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
@cindex time zone item
A @dfn{time zone item} specifies an international time zone, indicated
-by a small set of letters, e.g., @samp{UTC} for Coordinated Universal
+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 are obsolescent and are not recommended, because they
+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
projects / chaz / tar / blobdiff