Merge from vendor branch BINUTILS:
[dragonfly.git] / contrib / cvs-1.12 / doc / getdate-cvs.texi
1 @c This file is generated via a rule in Makefile.am from the
2 @c getdate.texi file.
3 @c
4 @c *** DO NOT EDIT THIS FILE DIRECTLY ***
5 @c
6 @c Edit getdate.texi instead.
7
8 @c GNU date syntax documentation
9
10 @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
11 @c 2003, 2004, 2005 Free Software Foundation, Inc.
12
13 @c Permission is granted to copy, distribute and/or modify this document
14 @c under the terms of the GNU Free Documentation License, Version 1.1 or
15 @c any later version published by the Free Software Foundation; with no
16 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
17 @c Texts.  A copy of the license is included in the ``GNU Free
18 @c Documentation License'' file as part of this distribution.
19
20 @node Date input formats
21 @appendixsec Date input formats
22
23 @cindex date input formats
24 @findex get_date
25
26 First, a quote:
27
28 @quotation
29 Our units of temporal measurement, from seconds on up to months, are so
30 complicated, asymmetrical and disjunctive so as to make coherent mental
31 reckoning in time all but impossible.  Indeed, had some tyrannical god
32 contrived to enslave our minds to time, to make it all but impossible
33 for us to escape subjection to sodden routines and unpleasant surprises,
34 he could hardly have done better than handing down our present system.
35 It is like a set of trapezoidal building blocks, with no vertical or
36 horizontal surfaces, like a language in which the simplest thought
37 demands ornate constructions, useless particles and lengthy
38 circumlocutions.  Unlike the more successful patterns of language and
39 science, which enable us to face experience boldly or at least
40 level-headedly, our system of temporal calculation silently and
41 persistently encourages our terror of time.
42
43 @dots{}  It is as though architects had to measure length in feet, width
44 in meters and height in ells; as though basic instruction manuals
45 demanded a knowledge of five different languages.  It is no wonder then
46 that we often look into our own immediate past or future, last Tuesday
47 or a week from Sunday, with feelings of helpless confusion.  @dots{}
48
49 --- Robert Grudin, @cite{Time and the Art of Living}.
50 @end quotation
51
52 This section describes the textual date representations that @sc{gnu}
53 programs accept.  These are the strings you, as a user, can supply as
54 arguments to the various programs.  The C interface (via the
55 @code{get_date} function) is not described here.
56
57 @menu
58 * General date syntax::            Common rules.
59 * Calendar date items::            19 Dec 1994.
60 * Time of day items::              9:20pm.
61 * Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
62 * Day of week items::              Monday and others.
63 * Relative items in date strings:: next tuesday, 2 years ago.
64 * Pure numbers in date strings::   19931219, 1440.
65 * Seconds since the Epoch::        @@1078100502.
66 * Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
67 * Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
68 @end menu
69
70
71 @node General date syntax
72 @appendixsubsec 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 the @command{date} command
124 is not always acceptable as a date string,
125 not only because of the language problem, but also because there is no
126 standard meaning for time zone items like @samp{IST}.  When using
127 @command{date} to generate a date string intended to be parsed later,
128 specify a date format that is independent of language and that does not
129 use time zone items other than @samp{UTC} and @samp{Z}.  Here are some
130 ways to do this:
131
132 @example
133 $ LC_ALL=C TZ=UTC0 date
134 Mon Mar  1 00:21:42 UTC 2004
135 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
136 2004-03-01 00:21:42Z
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 Sun, 29 Feb 2004 16:21:42 -0800
141 $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
142 2004-02-29 16:21:42 -0800
143 $ date +'@@%s.%N'  # %s and %N are GNU extensions.
144 @@1078100502.692722128
145 @end example
146
147 @cindex case, ignored in dates
148 @cindex comments, in dates
149 Alphabetic case is completely ignored in dates.  Comments may be introduced
150 between round parentheses, as long as included parentheses are properly
151 nested.  Hyphens not followed by a digit are currently ignored.  Leading
152 zeros on numbers are ignored.
153
154
155 @node Calendar date items
156 @appendixsubsec Calendar date items
157
158 @cindex calendar date item
159
160 A @dfn{calendar date item} specifies a day of the year.  It is
161 specified differently, depending on whether the month is specified
162 numerically or literally.  All these strings specify the same calendar date:
163
164 @example
165 1972-09-24     # @sc{iso} 8601.
166 72-9-24        # Assume 19xx for 69 through 99,
167                # 20xx for 00 through 68.
168 72-09-24       # Leading zeros are ignored.
169 9/24/72        # Common U.S. writing.
170 24 September 1972
171 24 Sept 72     # September has a special abbreviation.
172 24 Sep 72      # Three-letter abbreviations always allowed.
173 Sep 24, 1972
174 24-sep-72
175 24sep72
176 @end example
177
178 The year can also be omitted.  In this case, the last specified year is
179 used, or the current year if none.  For example:
180
181 @example
182 9/24
183 sep 24
184 @end example
185
186 Here are the rules.
187
188 @cindex @sc{iso} 8601 date format
189 @cindex date format, @sc{iso} 8601
190 For numeric months, the @sc{iso} 8601 format
191 @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
192 any positive number, @var{month} is a number between 01 and 12, and
193 @var{day} is a number between 01 and 31.  A leading zero must be present
194 if a number is less than ten.  If @var{year} is 68 or smaller, then 2000
195 is added to it; otherwise, if @var{year} is less than 100,
196 then 1900 is added to it.  The construct
197 @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
198 is accepted.  Also @samp{@var{month}/@var{day}}, omitting the year.
199
200 @cindex month names in date strings
201 @cindex abbreviations for months
202 Literal months may be spelled out in full: @samp{January},
203 @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
204 @samp{July}, @samp{August}, @samp{September}, @samp{October},
205 @samp{November} or @samp{December}.  Literal months may be abbreviated
206 to their first three letters, possibly followed by an abbreviating dot.
207 It is also permitted to write @samp{Sept} instead of @samp{September}.
208
209 When months are written literally, the calendar date may be given as any
210 of the following:
211
212 @example
213 @var{day} @var{month} @var{year}
214 @var{day} @var{month}
215 @var{month} @var{day} @var{year}
216 @var{day}-@var{month}-@var{year}
217 @end example
218
219 Or, omitting the year:
220
221 @example
222 @var{month} @var{day}
223 @end example
224
225
226 @node Time of day items
227 @appendixsubsec Time of day items
228
229 @cindex time of day item
230
231 A @dfn{time of day item} in date strings specifies the time on a given
232 day.  Here are some examples, all of which represent the same time:
233
234 @example
235 20:02:00.000000
236 20:02
237 8:02pm
238 20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
239 @end example
240
241 More generally, the time of day may be given as
242 @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
243 a number between 0 and 23, @var{minute} is a number between 0 and
244 59, and @var{second} is a number between 0 and 59 possibly followed by
245 @samp{.} or @samp{,} and a fraction containing one or more digits.
246 Alternatively,
247 @samp{:@var{second}} can be omitted, in which case it is taken to
248 be zero.
249
250 @findex am @r{in date strings}
251 @findex pm @r{in date strings}
252 @findex midnight @r{in date strings}
253 @findex noon @r{in date strings}
254 If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
255 or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
256 @samp{:@var{minute}} may be omitted (taken to be zero).  @samp{am}
257 indicates the first half of the day, @samp{pm} indicates the second
258 half of the day.  In this notation, 12 is the predecessor of 1:
259 midnight is @samp{12am} while noon is @samp{12pm}.
260 (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
261 as opposed to the old tradition derived from Latin
262 which uses @samp{12m} for noon and @samp{12pm} for midnight.)
263
264 @cindex time zone correction
265 @cindex minutes, time zone correction by
266 The time may alternatively be followed by a time zone correction,
267 expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
268 or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
269 of zone minutes.  You can also separate @var{hh} from @var{mm} with a colon.
270 When a time zone correction is given this way, it
271 forces interpretation of the time relative to
272 Coordinated Universal Time (@sc{utc}), overriding any previous
273 specification for the time zone or the local time zone.  For example,
274 @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
275 ahead of @sc{utc} (e.g., India).  The @var{minute}
276 part of the time of day may not be elided when a time zone correction
277 is used.  This is the best way to specify a time zone correction by
278 fractional parts of an hour.
279
280 Either @samp{am}/@samp{pm} or a time zone correction may be specified,
281 but not both.
282
283
284 @node Time zone items
285 @appendixsubsec Time zone items
286
287 @cindex time zone item
288
289 A @dfn{time zone item} specifies an international time zone, indicated
290 by a small set of letters, e.g., @samp{UTC} or @samp{Z}
291 for Coordinated Universal
292 Time.  Any included periods are ignored.  By following a
293 non-daylight-saving time zone by the string @samp{DST} in a separate
294 word (that is, separated by some white space), the corresponding
295 daylight saving time zone may be specified.
296 Alternatively, a non-daylight-saving time zone can be followed by a
297 time zone correction, to add the two values.  This is normally done
298 only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
299 @samp{+05:30}.
300
301 Time zone items other than @samp{UTC} and @samp{Z}
302 are obsolescent and are not recommended, because they
303 are ambiguous; for example, @samp{EST} has a different meaning in
304 Australia than in the United States.  Instead, it's better to use
305 unambiguous numeric time zone corrections like @samp{-0500}, as
306 described in the previous section.
307
308 If neither a time zone item nor a time zone correction is supplied,
309 time stamps are interpreted using the rules of the default time zone
310 (@pxref{Specifying time zone rules}).
311
312
313 @node Day of week items
314 @appendixsubsec 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 @appendixsubsec 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 @appendixsubsec 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 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 @appendixsubsec Seconds since the Epoch
449
450 If you precede a number with @samp{@@}, it represents an internal time
451 stamp as a count of seconds.  The number can contain an internal
452 decimal point (either @samp{.} or @samp{,}); any excess precision not
453 supported by the internal representation is truncated toward minus
454 infinity.  Such a number cannot be combined with any other date
455 item, as it specifies a complete time stamp.
456
457 @cindex beginning of time, for @acronym{POSIX}
458 @cindex epoch, for @acronym{POSIX}
459 Internally, computer times are represented as a count of seconds since
460 an epoch---a well-defined point of time.  On @acronym{GNU} and
461 @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
462 @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
463 00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
464 @acronym{POSIX}-compliant systems support such times as an extension
465 to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
466 represents 1969-12-31 23:59:59 @sc{utc}.
467
468 Traditional Unix systems count seconds with 32-bit two's-complement
469 integers and can represent times from 1901-12-13 20:45:52 through
470 2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
471 of seconds with nanosecond subcounts, and can represent all the times
472 in the known lifetime of the universe to a resolution of 1 nanosecond.
473
474 On most systems, these counts ignore the presence of leap seconds.
475 For example, on most systems @samp{@@915148799} represents 1998-12-31
476 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
477 @sc{utc}, and there is no way to represent the intervening leap second
478 1998-12-31 23:59:60 @sc{utc}.
479
480 @node Specifying time zone rules
481 @appendixsubsec Specifying time zone rules
482
483 @vindex TZ
484 Normally, dates are interpreted using the rules of the current time
485 zone, which in turn are specified by the @env{TZ} environment
486 variable, or by a system default if @env{TZ} is not set.  To specify a
487 different set of default time zone rules that apply just to one date,
488 start the date with a string of the form @samp{TZ="@var{rule}"}.  The
489 two quote characters (@samp{"}) must be present in the date, and any
490 quotes or backslashes within @var{rule} must be escaped by a
491 backslash.
492
493 For example, with the @acronym{GNU} @command{date} command you can
494 answer the question ``What time is it in New York when a Paris clock
495 shows 6:30am on October 31, 2004?'' by using a date beginning with
496 @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
497
498 @example
499 $ export TZ="America/New_York"
500 $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
501 Sun Oct 31 01:30:00 EDT 2004
502 @end example
503
504 In this example, the @option{--date} operand begins with its own
505 @env{TZ} setting, so the rest of that operand is processed according
506 to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
507 06:30} as if it were in Paris.  However, since the output of the
508 @command{date} command is processed according to the overall time zone
509 rules, it uses New York time.  (Paris was normally six hours ahead of
510 New York in 2004, but this example refers to a brief Halloween period
511 when the gap was five hours.)
512
513 A @env{TZ} value is a rule that typically names a location in the
514 @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
515 A recent catalog of location names appears in the
516 @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
517 Gateway}.  A few non-@acronym{GNU} hosts require a colon before a
518 location name in a @env{TZ} setting, e.g.,
519 @samp{TZ=":America/New_York"}.
520
521 The @samp{tz} database includes a wide variety of locations ranging
522 from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
523 if you are at sea and have your own private time zone, or if you are
524 using a non-@acronym{GNU} host that does not support the @samp{tz}
525 database, you may need to use a @acronym{POSIX} rule instead.  Simple
526 @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
527 daylight saving time; other rules can specify simple daylight saving
528 regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
529 libc, The GNU C Library}.
530
531 @node Authors of get_date
532 @appendixsubsec Authors of @code{get_date}
533
534 @cindex authors of @code{get_date}
535
536 @cindex Bellovin, Steven M.
537 @cindex Salz, Rich
538 @cindex Berets, Jim
539 @cindex MacKenzie, David
540 @cindex Meyering, Jim
541 @cindex Eggert, Paul
542 @code{get_date} was originally implemented by Steven M. Bellovin
543 (@email{smb@@research.att.com}) while at the University of North Carolina
544 at Chapel Hill.  The code was later tweaked by a couple of people on
545 Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
546 and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
547 revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
548 Paul Eggert and others.
549
550 @cindex Pinard, F.
551 @cindex Berry, K.
552 This chapter was originally produced by Fran@,{c}ois Pinard
553 (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
554 and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).