sync with .orig.tar.gz after removing all CLEANFILES
[alioth/cvs.git] / doc / getdate.texi
1 @c GNU date syntax documentation
2
3 @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
4 @c 2003, 2004, 2005 Free Software Foundation, Inc.
5
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.1 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
10 @c Texts.  A copy of the license is included in the ``GNU Free
11 @c Documentation License'' file as part of this distribution.
12
13 @node Date input formats
14 @chapter Date input formats
15
16 @cindex date input formats
17 @findex get_date
18
19 First, a quote:
20
21 @quotation
22 Our units of temporal measurement, from seconds on up to months, are so
23 complicated, asymmetrical and disjunctive so as to make coherent mental
24 reckoning in time all but impossible.  Indeed, had some tyrannical god
25 contrived to enslave our minds to time, to make it all but impossible
26 for us to escape subjection to sodden routines and unpleasant surprises,
27 he could hardly have done better than handing down our present system.
28 It is like a set of trapezoidal building blocks, with no vertical or
29 horizontal surfaces, like a language in which the simplest thought
30 demands ornate constructions, useless particles and lengthy
31 circumlocutions.  Unlike the more successful patterns of language and
32 science, which enable us to face experience boldly or at least
33 level-headedly, our system of temporal calculation silently and
34 persistently encourages our terror of time.
35
36 @dots{}  It is as though architects had to measure length in feet, width
37 in meters and height in ells; as though basic instruction manuals
38 demanded a knowledge of five different languages.  It is no wonder then
39 that we often look into our own immediate past or future, last Tuesday
40 or a week from Sunday, with feelings of helpless confusion.  @dots{}
41
42 --- Robert Grudin, @cite{Time and the Art of Living}.
43 @end quotation
44
45 This section describes the textual date representations that @sc{gnu}
46 programs accept.  These are the strings you, as a user, can supply as
47 arguments to the various programs.  The C interface (via the
48 @code{get_date} function) is not described here.
49
50 @menu
51 * General date syntax::            Common rules.
52 * Calendar date items::            19 Dec 1994.
53 * Time of day items::              9:20pm.
54 * Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
55 * Day of week items::              Monday and others.
56 * Relative items in date strings:: next tuesday, 2 years ago.
57 * Pure numbers in date strings::   19931219, 1440.
58 * Seconds since the Epoch::        @@1078100502.
59 * Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
60 * Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
61 @end menu
62
63
64 @node General date syntax
65 @section General date syntax
66
67 @cindex general date syntax
68
69 @cindex items in date strings
70 A @dfn{date} is a string, possibly empty, containing many items
71 separated by whitespace.  The whitespace may be omitted when no
72 ambiguity arises.  The empty string means the beginning of today (i.e.,
73 midnight).  Order of the items is immaterial.  A date string may contain
74 many flavors of items:
75
76 @itemize @bullet
77 @item calendar date items
78 @item time of day items
79 @item time zone items
80 @item day of the week items
81 @item relative items
82 @item pure numbers.
83 @end itemize
84
85 @noindent We describe each of these item types in turn, below.
86
87 @cindex numbers, written-out
88 @cindex ordinal numbers
89 @findex first @r{in date strings}
90 @findex next @r{in date strings}
91 @findex last @r{in date strings}
92 A few ordinal numbers may be written out in words in some contexts.  This is
93 most useful for specifying day of the week items or relative items (see
94 below).  Among the most commonly used ordinal numbers, the word
95 @samp{last} stands for @math{-1}, @samp{this} stands for 0, and
96 @samp{first} and @samp{next} both stand for 1.  Because the word
97 @samp{second} stands for the unit of time there is no way to write the
98 ordinal number 2, but for convenience @samp{third} stands for 3,
99 @samp{fourth} for 4, @samp{fifth} for 5,
100 @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
101 @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
102 @samp{twelfth} for 12.
103
104 @cindex months, written-out
105 When a month is written this way, it is still considered to be written
106 numerically, instead of being ``spelled in full''; this changes the
107 allowed strings.
108
109 @cindex language, in dates
110 In the current implementation, only English is supported for words and
111 abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
112 @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
113
114 @cindex language, in dates
115 @cindex time zone item
116 The output of the @command{date} command
117 is not always acceptable as a date string,
118 not only because of the language problem, but also because there is no
119 standard meaning for time zone items like @samp{IST}.  When using
120 @command{date} to generate a date string intended to be parsed later,
121 specify a date format that is independent of language and that does not
122 use time zone items other than @samp{UTC} and @samp{Z}.  Here are some
123 ways to do this:
124
125 @example
126 $ LC_ALL=C TZ=UTC0 date
127 Mon Mar  1 00:21:42 UTC 2004
128 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
129 2004-03-01 00:21:42Z
130 $ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
131 2004-02-29 16:21:42,692722128-0800
132 $ date --rfc-2822  # a GNU extension
133 Sun, 29 Feb 2004 16:21:42 -0800
134 $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
135 2004-02-29 16:21:42 -0800
136 $ date +'@@%s.%N'  # %s and %N are GNU extensions.
137 @@1078100502.692722128
138 @end example
139
140 @cindex case, ignored in dates
141 @cindex comments, in dates
142 Alphabetic case is completely ignored in dates.  Comments may be introduced
143 between round parentheses, as long as included parentheses are properly
144 nested.  Hyphens not followed by a digit are currently ignored.  Leading
145 zeros on numbers are ignored.
146
147
148 @node Calendar date items
149 @section Calendar date items
150
151 @cindex calendar date item
152
153 A @dfn{calendar date item} specifies a day of the year.  It is
154 specified differently, depending on whether the month is specified
155 numerically or literally.  All these strings specify the same calendar date:
156
157 @example
158 1972-09-24     # @sc{iso} 8601.
159 72-9-24        # Assume 19xx for 69 through 99,
160                # 20xx for 00 through 68.
161 72-09-24       # Leading zeros are ignored.
162 9/24/72        # Common U.S. writing.
163 24 September 1972
164 24 Sept 72     # September has a special abbreviation.
165 24 Sep 72      # Three-letter abbreviations always allowed.
166 Sep 24, 1972
167 24-sep-72
168 24sep72
169 @end example
170
171 The year can also be omitted.  In this case, the last specified year is
172 used, or the current year if none.  For example:
173
174 @example
175 9/24
176 sep 24
177 @end example
178
179 Here are the rules.
180
181 @cindex @sc{iso} 8601 date format
182 @cindex date format, @sc{iso} 8601
183 For numeric months, the @sc{iso} 8601 format
184 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
185 any positive number, @var{month} is a number between 01 and 12, and
186 @var{day} is a number between 01 and 31.  A leading zero must be present
187 if a number is less than ten.  If @var{year} is 68 or smaller, then 2000
188 is added to it; otherwise, if @var{year} is less than 100,
189 then 1900 is added to it.  The construct
190 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
191 is accepted.  Also @samp{@var{month}/@var{day}}, omitting the year.
192
193 @cindex month names in date strings
194 @cindex abbreviations for months
195 Literal months may be spelled out in full: @samp{January},
196 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
197 @samp{July}, @samp{August}, @samp{September}, @samp{October},
198 @samp{November} or @samp{December}.  Literal months may be abbreviated
199 to their first three letters, possibly followed by an abbreviating dot.
200 It is also permitted to write @samp{Sept} instead of @samp{September}.
201
202 When months are written literally, the calendar date may be given as any
203 of the following:
204
205 @example
206 @var{day} @var{month} @var{year}
207 @var{day} @var{month}
208 @var{month} @var{day} @var{year}
209 @var{day}-@var{month}-@var{year}
210 @end example
211
212 Or, omitting the year:
213
214 @example
215 @var{month} @var{day}
216 @end example
217
218
219 @node Time of day items
220 @section Time of day items
221
222 @cindex time of day item
223
224 A @dfn{time of day item} in date strings specifies the time on a given
225 day.  Here are some examples, all of which represent the same time:
226
227 @example
228 20:02:00.000000
229 20:02
230 8:02pm
231 20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
232 @end example
233
234 More generally, the time of day may be given as
235 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
236 a number between 0 and 23, @var{minute} is a number between 0 and
237 59, and @var{second} is a number between 0 and 59 possibly followed by
238 @samp{.} or @samp{,} and a fraction containing one or more digits.
239 Alternatively,
240 @samp{:@var{second}} can be omitted, in which case it is taken to
241 be zero.
242
243 @findex am @r{in date strings}
244 @findex pm @r{in date strings}
245 @findex midnight @r{in date strings}
246 @findex noon @r{in date strings}
247 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
248 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
249 @samp{:@var{minute}} may be omitted (taken to be zero).  @samp{am}
250 indicates the first half of the day, @samp{pm} indicates the second
251 half of the day.  In this notation, 12 is the predecessor of 1:
252 midnight is @samp{12am} while noon is @samp{12pm}.
253 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
254 as opposed to the old tradition derived from Latin
255 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
256
257 @cindex time zone correction
258 @cindex minutes, time zone correction by
259 The time may alternatively be followed by a time zone correction,
260 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
261 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
262 of zone minutes.  You can also separate @var{hh} from @var{mm} with a colon.
263 When a time zone correction is given this way, it
264 forces interpretation of the time relative to
265 Coordinated Universal Time (@sc{utc}), overriding any previous
266 specification for the time zone or the local time zone.  For example,
267 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
268 ahead of @sc{utc} (e.g., India).  The @var{minute}
269 part of the time of day may not be elided when a time zone correction
270 is used.  This is the best way to specify a time zone correction by
271 fractional parts of an hour.
272
273 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
274 but not both.
275
276
277 @node Time zone items
278 @section Time zone items
279
280 @cindex time zone item
281
282 A @dfn{time zone item} specifies an international time zone, indicated
283 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
284 for Coordinated Universal
285 Time.  Any included periods are ignored.  By following a
286 non-daylight-saving time zone by the string @samp{DST} in a separate
287 word (that is, separated by some white space), the corresponding
288 daylight saving time zone may be specified.
289 Alternatively, a non-daylight-saving time zone can be followed by a
290 time zone correction, to add the two values.  This is normally done
291 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
292 @samp{+05:30}.
293
294 Time zone items other than @samp{UTC} and @samp{Z}
295 are obsolescent and are not recommended, because they
296 are ambiguous; for example, @samp{EST} has a different meaning in
297 Australia than in the United States.  Instead, it's better to use
298 unambiguous numeric time zone corrections like @samp{-0500}, as
299 described in the previous section.
300
301 If neither a time zone item nor a time zone correction is supplied,
302 time stamps are interpreted using the rules of the default time zone
303 (@pxref{Specifying time zone rules}).
304
305
306 @node Day of week items
307 @section Day of week items
308
309 @cindex day of week item
310
311 The explicit mention of a day of the week will forward the date
312 (only if necessary) to reach that day of the week in the future.
313
314 Days of the week may be spelled out in full: @samp{Sunday},
315 @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
316 @samp{Friday} or @samp{Saturday}.  Days may be abbreviated to their
317 first three letters, optionally followed by a period.  The special
318 abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
319 @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
320 also allowed.
321
322 @findex next @var{day}
323 @findex last @var{day}
324 A number may precede a day of the week item to move forward
325 supplementary weeks.  It is best used in expression like @samp{third
326 monday}.  In this context, @samp{last @var{day}} or @samp{next
327 @var{day}} is also acceptable; they move one week before or after
328 the day that @var{day} by itself would represent.
329
330 A comma following a day of the week item is ignored.
331
332
333 @node Relative items in date strings
334 @section Relative items in date strings
335
336 @cindex relative items in date strings
337 @cindex displacement of dates
338
339 @dfn{Relative items} adjust a date (or the current date if none) forward
340 or backward.  The effects of relative items accumulate.  Here are some
341 examples:
342
343 @example
344 1 year
345 1 year ago
346 3 years
347 2 days
348 @end example
349
350 @findex year @r{in date strings}
351 @findex month @r{in date strings}
352 @findex fortnight @r{in date strings}
353 @findex week @r{in date strings}
354 @findex day @r{in date strings}
355 @findex hour @r{in date strings}
356 @findex minute @r{in date strings}
357 The unit of time displacement may be selected by the string @samp{year}
358 or @samp{month} for moving by whole years or months.  These are fuzzy
359 units, as years and months are not all of equal duration.  More precise
360 units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
361 days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
362 @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
363 @samp{sec} worth one second.  An @samp{s} suffix on these units is
364 accepted and ignored.
365
366 @findex ago @r{in date strings}
367 The unit of time may be preceded by a multiplier, given as an optionally
368 signed number.  Unsigned numbers are taken as positively signed.  No
369 number at all implies 1 for a multiplier.  Following a relative item by
370 the string @samp{ago} is equivalent to preceding the unit by a
371 multiplier with value @math{-1}.
372
373 @findex day @r{in date strings}
374 @findex tomorrow @r{in date strings}
375 @findex yesterday @r{in date strings}
376 The string @samp{tomorrow} is worth one day in the future (equivalent
377 to @samp{day}), the string @samp{yesterday} is worth
378 one day in the past (equivalent to @samp{day ago}).
379
380 @findex now @r{in date strings}
381 @findex today @r{in date strings}
382 @findex this @r{in date strings}
383 The strings @samp{now} or @samp{today} are relative items corresponding
384 to zero-valued time displacement, these strings come from the fact
385 a zero-valued time displacement represents the current time when not
386 otherwise changed by previous items.  They may be used to stress other
387 items, like in @samp{12:00 today}.  The string @samp{this} also has
388 the meaning of a zero-valued time displacement, but is preferred in
389 date strings like @samp{this thursday}.
390
391 When a relative item causes the resulting date to cross a boundary
392 where the clocks were adjusted, typically for daylight saving time,
393 the resulting date and time are adjusted accordingly.
394
395 The fuzz in units can cause problems with relative items.  For
396 example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
397 because 2003-06-31 is an invalid date.  To determine the previous
398 month more reliably, you can ask for the month before the 15th of the
399 current month.  For example:
400
401 @example
402 $ date -R
403 Thu, 31 Jul 2003 13:02:39 -0700
404 $ date --date='-1 month' +'Last month was %B?'
405 Last month was July?
406 $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
407 Last month was June!
408 @end example
409
410 Also, take care when manipulating dates around clock changes such as
411 daylight saving leaps.  In a few cases these have added or subtracted
412 as much as 24 hours from the clock, so it is often wise to adopt
413 universal time by setting the @env{TZ} environment variable to
414 @samp{UTC0} before embarking on calendrical calculations.
415
416 @node Pure numbers in date strings
417 @section Pure numbers in date strings
418
419 @cindex pure numbers in date strings
420
421 The precise interpretation of a pure decimal number depends
422 on the context in the date string.
423
424 If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
425 other calendar date item (@pxref{Calendar date items}) appears before it
426 in the date string, then @var{yyyy} is read as the year, @var{mm} as the
427 month number and @var{dd} as the day of the month, for the specified
428 calendar date.
429
430 If the decimal number is of the form @var{hh}@var{mm} and no other time
431 of day item appears before it in the date string, then @var{hh} is read
432 as the hour of the day and @var{mm} as the minute of the hour, for the
433 specified time of day.  @var{mm} can also be omitted.
434
435 If both a calendar date and a time of day appear to the left of a number
436 in the date string, but no relative item, then the number overrides the
437 year.
438
439
440 @node Seconds since the Epoch
441 @section Seconds since the Epoch
442
443 If you precede a number with @samp{@@}, it represents an internal time
444 stamp as a count of seconds.  The number can contain an internal
445 decimal point (either @samp{.} or @samp{,}); any excess precision not
446 supported by the internal representation is truncated toward minus
447 infinity.  Such a number cannot be combined with any other date
448 item, as it specifies a complete time stamp.
449
450 @cindex beginning of time, for @acronym{POSIX}
451 @cindex epoch, for @acronym{POSIX}
452 Internally, computer times are represented as a count of seconds since
453 an epoch---a well-defined point of time.  On @acronym{GNU} and
454 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
455 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
456 00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
457 @acronym{POSIX}-compliant systems support such times as an extension
458 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
459 represents 1969-12-31 23:59:59 @sc{utc}.
460
461 Traditional Unix systems count seconds with 32-bit two's-complement
462 integers and can represent times from 1901-12-13 20:45:52 through
463 2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
464 of seconds with nanosecond subcounts, and can represent all the times
465 in the known lifetime of the universe to a resolution of 1 nanosecond.
466
467 On most systems, these counts ignore the presence of leap seconds.
468 For example, on most systems @samp{@@915148799} represents 1998-12-31
469 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
470 @sc{utc}, and there is no way to represent the intervening leap second
471 1998-12-31 23:59:60 @sc{utc}.
472
473 @node Specifying time zone rules
474 @section Specifying time zone rules
475
476 @vindex TZ
477 Normally, dates are interpreted using the rules of the current time
478 zone, which in turn are specified by the @env{TZ} environment
479 variable, or by a system default if @env{TZ} is not set.  To specify a
480 different set of default time zone rules that apply just to one date,
481 start the date with a string of the form @samp{TZ="@var{rule}"}.  The
482 two quote characters (@samp{"}) must be present in the date, and any
483 quotes or backslashes within @var{rule} must be escaped by a
484 backslash.
485
486 For example, with the @acronym{GNU} @command{date} command you can
487 answer the question ``What time is it in New York when a Paris clock
488 shows 6:30am on October 31, 2004?'' by using a date beginning with
489 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
490
491 @example
492 $ export TZ="America/New_York"
493 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
494 Sun Oct 31 01:30:00 EDT 2004
495 @end example
496
497 In this example, the @option{--date} operand begins with its own
498 @env{TZ} setting, so the rest of that operand is processed according
499 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
500 06:30} as if it were in Paris.  However, since the output of the
501 @command{date} command is processed according to the overall time zone
502 rules, it uses New York time.  (Paris was normally six hours ahead of
503 New York in 2004, but this example refers to a brief Halloween period
504 when the gap was five hours.)
505
506 A @env{TZ} value is a rule that typically names a location in the
507 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
508 A recent catalog of location names appears in the
509 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
510 Gateway}.  A few non-@acronym{GNU} hosts require a colon before a
511 location name in a @env{TZ} setting, e.g.,
512 @samp{TZ=":America/New_York"}.
513
514 The @samp{tz} database includes a wide variety of locations ranging
515 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
516 if you are at sea and have your own private time zone, or if you are
517 using a non-@acronym{GNU} host that does not support the @samp{tz}
518 database, you may need to use a @acronym{POSIX} rule instead.  Simple
519 @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
520 daylight saving time; other rules can specify simple daylight saving
521 regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
522 libc, The GNU C Library}.
523
524 @node Authors of get_date
525 @section Authors of @code{get_date}
526
527 @cindex authors of @code{get_date}
528
529 @cindex Bellovin, Steven M.
530 @cindex Salz, Rich
531 @cindex Berets, Jim
532 @cindex MacKenzie, David
533 @cindex Meyering, Jim
534 @cindex Eggert, Paul
535 @code{get_date} was originally implemented by Steven M. Bellovin
536 (@email{smb@@research.att.com}) while at the University of North Carolina
537 at Chapel Hill.  The code was later tweaked by a couple of people on
538 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
539 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
540 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
541 Paul Eggert and others.
542
543 @cindex Pinard, F.
544 @cindex Berry, K.
545 This chapter was originally produced by Fran@,{c}ois Pinard
546 (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
547 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).