@c GNU date syntax documentation
-@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
-@c 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc.
+@c Copyright (C) 1994-2006, 2009-2012 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.3 or
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
+* Combined date and time of day items:: 1972-09-24T20:02:00,000000-0500
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
@item calendar date items
@item time of day items
@item time zone items
+@item combined date and time of day items
@item day of the week items
@item relative items
@item pure numbers.
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
+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
+use time zone items other than @samp{UTC} and @samp{Z}@. Here are some
ways to do this:
@example
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 | tr T ' ' # --iso-8601 is a GNU extension.
-2004-02-29 16:21:42,692722128-0800
+$ date --rfc-3339=ns # --rfc-3339 is a GNU extension.
+2004-02-29 16:21:42.692722128-08:00
$ 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.
nested. Hyphens not followed by a digit are currently ignored. Leading
zeros on numbers are ignored.
+@cindex leap seconds
Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
rejected. In the typical case of a host that does not support leap
seconds, a time like @samp{23:59:60} is rejected even if it
20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
@end example
+@cindex leap seconds
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
(@pxref{Specifying time zone rules}).
+@node Combined date and time of day items
+@section Combined date and time of day items
+
+@cindex combined date and time of day item
+
+A @dfn{combined date and time of day item} specifies the time on a
+specific day of the year. This type is needed for formats that cannot
+be represented by individual calendar date (@pxref{Calendar date items})
+and time of day (@pxref{Time of day items}) items due to ambiguity.
+
+@example
+# ISO 8601 extended date and time of day format
+1972-09-24T20:02:00,000000-0500
+@end example
+
+@cindex @sc{iso} 8601 date and time of day format
+@cindex date and time of day format, @sc{iso} 8601
+
+The @sc{iso} 8601 extended date and time of day format is an @sc{iso}
+8601 date, a @samp{T} character separator, followed by an @sc{iso} 8601 time
+of day.
+
+
@node Day of week items
@section Day of week items
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}
+@cindex beginning of time, for POSIX
+@cindex epoch, for 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
+an epoch---a well-defined point of time. On GNU and
+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}
+00:00:01 @sc{utc}, and so forth. GNU and most other
+POSIX-compliant systems support such times as an extension
+to 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
of seconds with nanosecond subcounts, and can represent all the times
in the known lifetime of the universe to a resolution of 1 nanosecond.
+@cindex leap seconds
On most hosts, these counts ignore the presence of leap seconds.
For example, on most hosts @samp{@@915148799} represents 1998-12-31
23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
quotes or backslashes within @var{rule} must be escaped by a
backslash.
-For example, with the @acronym{GNU} @command{date} command you can
+For example, with the 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:
@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
+Gateway}. A few non-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
+using a non-GNU host that does not support the @samp{tz}
+database, you may need to use a POSIX rule instead. Simple
+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}.
@cindex MacKenzie, David
@cindex Meyering, Jim
@cindex Eggert, Paul
-@code{get_date} was originally implemented by Steven M. Bellovin
+@code{parse_datetime} started life as @code{getdate}, as 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 @sc{gnu} system were made by David MacKenzie, Jim Meyering,
-Paul Eggert and others, including renaming it to @code{parse_datetime}
-to avoid confusion with the Posix function @code{getdate}.
+Paul Eggert and others, including renaming it to @code{get_date} to
+avoid a conflict with the alternative Posix function @code{getdate},
+and a later rename to @code{parse_datetime}. The Posix function
+@code{getdate} can parse more locale-specific dates using
+@code{strptime}, but relies on an environment variable and external
+file, and lacks the thread-safety of @code{parse_datetime}.
@cindex Pinard, F.
@cindex Berry, K.
This chapter was originally produced by Fran@,{c}ois Pinard
(@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
-and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
+and then edited by K. Berry (@email{kb@@cs.umb.edu}).
projects / gnulib.git / blobdiff