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