1
1
@c GNU date syntax documentation
3
@c Copyright (C) 1994-2006, 2009-2011 Free Software Foundation, Inc.
3
@c Copyright (C) 1994-2006, 2009-2012 Free Software Foundation, Inc.
5
5
@c Permission is granted to copy, distribute and/or modify this document
6
6
@c under the terms of the GNU Free Documentation License, Version 1.3 or
117
117
The output of the @command{date} command
118
118
is not always acceptable as a date string,
119
119
not only because of the language problem, but also because there is no
120
standard meaning for time zone items like @samp{IST}. When using
120
standard meaning for time zone items like @samp{IST}@. When using
121
121
@command{date} to generate a date string intended to be parsed later,
122
122
specify a date format that is independent of language and that does not
123
use time zone items other than @samp{UTC} and @samp{Z}. Here are some
123
use time zone items other than @samp{UTC} and @samp{Z}@. Here are some
145
145
nested. Hyphens not followed by a digit are currently ignored. Leading
146
146
zeros on numbers are ignored.
148
149
Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
149
150
rejected. In the typical case of a host that does not support leap
150
151
seconds, a time like @samp{23:59:60} is rejected even if it
237
238
20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
240
242
More generally, the time of day may be given as
241
243
@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
242
244
a number between 0 and 23, @var{minute} is a number between 0 and
480
482
infinity. Such a number cannot be combined with any other date
481
483
item, as it specifies a complete time stamp.
483
@cindex beginning of time, for @acronym{POSIX}
484
@cindex epoch, for @acronym{POSIX}
485
@cindex beginning of time, for POSIX
486
@cindex epoch, for POSIX
485
487
Internally, computer times are represented as a count of seconds since
486
an epoch---a well-defined point of time. On @acronym{GNU} and
487
@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
488
an epoch---a well-defined point of time. On GNU and
489
POSIX systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
488
490
@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
489
00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
490
@acronym{POSIX}-compliant systems support such times as an extension
491
to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
491
00:00:01 @sc{utc}, and so forth. GNU and most other
492
POSIX-compliant systems support such times as an extension
493
to POSIX, using negative counts, so that @samp{@@-1}
492
494
represents 1969-12-31 23:59:59 @sc{utc}.
494
496
Traditional Unix systems count seconds with 32-bit two's-complement
497
499
of seconds with nanosecond subcounts, and can represent all the times
498
500
in the known lifetime of the universe to a resolution of 1 nanosecond.
500
503
On most hosts, these counts ignore the presence of leap seconds.
501
504
For example, on most hosts @samp{@@915148799} represents 1998-12-31
502
505
23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
516
519
quotes or backslashes within @var{rule} must be escaped by a
519
For example, with the @acronym{GNU} @command{date} command you can
522
For example, with the GNU @command{date} command you can
520
523
answer the question ``What time is it in New York when a Paris clock
521
524
shows 6:30am on October 31, 2004?'' by using a date beginning with
522
525
@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
540
543
@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
541
544
A recent catalog of location names appears in the
542
545
@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
543
Gateway}. A few non-@acronym{GNU} hosts require a colon before a
546
Gateway}. A few non-GNU hosts require a colon before a
544
547
location name in a @env{TZ} setting, e.g.,
545
548
@samp{TZ=":America/New_York"}.
547
550
The @samp{tz} database includes a wide variety of locations ranging
548
551
from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
549
552
if you are at sea and have your own private time zone, or if you are
550
using a non-@acronym{GNU} host that does not support the @samp{tz}
551
database, you may need to use a @acronym{POSIX} rule instead. Simple
552
@acronym{POSIX} rules like @samp{UTC0} specify a time zone without
553
using a non-GNU host that does not support the @samp{tz}
554
database, you may need to use a POSIX rule instead. Simple
555
POSIX rules like @samp{UTC0} specify a time zone without
553
556
daylight saving time; other rules can specify simple daylight saving
554
557
regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
555
558
libc, The GNU C Library}.
585
588
@cindex Berry, K.
586
589
This chapter was originally produced by Fran@,{c}ois Pinard
587
590
(@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
588
and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
591
and then edited by K. Berry (@email{kb@@cs.umb.edu}).
added
removed
doc/parse-datetime.texi
