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