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