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 26First, a quote: 27 28@quotation 29Our units of temporal measurement, from seconds on up to months, are so 30complicated, asymmetrical and disjunctive so as to make coherent mental 31reckoning in time all but impossible. Indeed, had some tyrannical god 32contrived to enslave our minds to time, to make it all but impossible 33for us to escape subjection to sodden routines and unpleasant surprises, 34he could hardly have done better than handing down our present system. 35It is like a set of trapezoidal building blocks, with no vertical or 36horizontal surfaces, like a language in which the simplest thought 37demands ornate constructions, useless particles and lengthy 38circumlocutions. Unlike the more successful patterns of language and 39science, which enable us to face experience boldly or at least 40level-headedly, our system of temporal calculation silently and 41persistently encourages our terror of time. 42 43@dots{} It is as though architects had to measure length in feet, width 44in meters and height in ells; as though basic instruction manuals 45demanded a knowledge of five different languages. It is no wonder then 46that we often look into our own immediate past or future, last Tuesday 47or 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 52This section describes the textual date representations that @sc{gnu} 53programs accept. These are the strings you, as a user, can supply as 54arguments 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 77A @dfn{date} is a string, possibly empty, containing many items 78separated by whitespace. The whitespace may be omitted when no 79ambiguity arises. The empty string means the beginning of today (i.e., 80midnight). Order of the items is immaterial. A date string may contain 81many 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} 99A few ordinal numbers may be written out in words in some contexts. This is 100most useful for specifying day of the week items or relative items (see 101below). 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 105ordinal 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 112When a month is written this way, it is still considered to be written 113numerically, instead of being ``spelled in full''; this changes the 114allowed strings. 115 116@cindex language, in dates 117In the current implementation, only English is supported for words and 118abbreviations 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 123The output of the @command{date} command 124is not always acceptable as a date string, 125not only because of the language problem, but also because there is no 126standard meaning for time zone items like @samp{IST}. When using 127@command{date} to generate a date string intended to be parsed later, 128specify a date format that is independent of language and that does not 129use time zone items other than @samp{UTC} and @samp{Z}. Here are some 130ways to do this: 131 132@example 133$ LC_ALL=C TZ=UTC0 date 134Mon Mar 1 00:21:42 UTC 2004 135$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 1362004-03-01 00:21:42Z 137$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 1382004-02-29 16:21:42,692722128-0800 139$ date --rfc-2822 # a GNU extension 140Sun, 29 Feb 2004 16:21:42 -0800 141$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 1422004-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 149Alphabetic case is completely ignored in dates. Comments may be introduced 150between round parentheses, as long as included parentheses are properly 151nested. Hyphens not followed by a digit are currently ignored. Leading 152zeros on numbers are ignored. 153 154 155@node Calendar date items 156@appendixsubsec Calendar date items 157 158@cindex calendar date item 159 160A @dfn{calendar date item} specifies a day of the year. It is 161specified differently, depending on whether the month is specified 162numerically or literally. All these strings specify the same calendar date: 163 164@example 1651972-09-24 # @sc{iso} 8601. 16672-9-24 # Assume 19xx for 69 through 99, 167 # 20xx for 00 through 68. 16872-09-24 # Leading zeros are ignored. 1699/24/72 # Common U.S. writing. 17024 September 1972 17124 Sept 72 # September has a special abbreviation. 17224 Sep 72 # Three-letter abbreviations always allowed. 173Sep 24, 1972 17424-sep-72 17524sep72 176@end example 177 178The year can also be omitted. In this case, the last specified year is 179used, or the current year if none. For example: 180 181@example 1829/24 183sep 24 184@end example 185 186Here are the rules. 187 188@cindex @sc{iso} 8601 date format 189@cindex date format, @sc{iso} 8601 190For numeric months, the @sc{iso} 8601 format 191@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 192any 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 194if a number is less than ten. If @var{year} is 68 or smaller, then 2000 195is added to it; otherwise, if @var{year} is less than 100, 196then 1900 is added to it. The construct 197@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 198is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 199 200@cindex month names in date strings 201@cindex abbreviations for months 202Literal 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 206to their first three letters, possibly followed by an abbreviating dot. 207It is also permitted to write @samp{Sept} instead of @samp{September}. 208 209When months are written literally, the calendar date may be given as any 210of 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 219Or, 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 231A @dfn{time of day item} in date strings specifies the time on a given 232day. Here are some examples, all of which represent the same time: 233 234@example 23520:02:00.000000 23620:02 2378:02pm 23820:02-0500 # In @sc{est} (U.S. Eastern Standard Time). 239@end example 240 241More generally, the time of day may be given as 242@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is 243a number between 0 and 23, @var{minute} is a number between 0 and 24459, 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. 246Alternatively, 247@samp{:@var{second}} can be omitted, in which case it is taken to 248be 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} 254If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} 255or @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} 257indicates the first half of the day, @samp{pm} indicates the second 258half of the day. In this notation, 12 is the predecessor of 1: 259midnight is @samp{12am} while noon is @samp{12pm}. 260(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, 261as opposed to the old tradition derived from Latin 262which uses @samp{12m} for noon and @samp{12pm} for midnight.) 263 264@cindex time zone correction 265@cindex minutes, time zone correction by 266The time may alternatively be followed by a time zone correction, 267expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} 268or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number 269of zone minutes. You can also separate @var{hh} from @var{mm} with a colon. 270When a time zone correction is given this way, it 271forces interpretation of the time relative to 272Coordinated Universal Time (@sc{utc}), overriding any previous 273specification 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 275ahead of @sc{utc} (e.g., India). The @var{minute} 276part of the time of day may not be elided when a time zone correction 277is used. This is the best way to specify a time zone correction by 278fractional parts of an hour. 279 280Either @samp{am}/@samp{pm} or a time zone correction may be specified, 281but not both. 282 283 284@node Time zone items 285@appendixsubsec Time zone items 286 287@cindex time zone item 288 289A @dfn{time zone item} specifies an international time zone, indicated 290by a small set of letters, e.g., @samp{UTC} or @samp{Z} 291for Coordinated Universal 292Time. Any included periods are ignored. By following a 293non-daylight-saving time zone by the string @samp{DST} in a separate 294word (that is, separated by some white space), the corresponding 295daylight saving time zone may be specified. 296Alternatively, a non-daylight-saving time zone can be followed by a 297time zone correction, to add the two values. This is normally done 298only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to 299@samp{+05:30}. 300 301Time zone items other than @samp{UTC} and @samp{Z} 302are obsolescent and are not recommended, because they 303are ambiguous; for example, @samp{EST} has a different meaning in 304Australia than in the United States. Instead, it's better to use 305unambiguous numeric time zone corrections like @samp{-0500}, as 306described in the previous section. 307 308If neither a time zone item nor a time zone correction is supplied, 309time 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 318The 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 321Days 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 324first three letters, optionally followed by a period. The special 325abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 326@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 327also allowed. 328 329@findex next @var{day} 330@findex last @var{day} 331A number may precede a day of the week item to move forward 332supplementary weeks. It is best used in expression like @samp{third 333monday}. In this context, @samp{last @var{day}} or @samp{next 334@var{day}} is also acceptable; they move one week before or after 335the day that @var{day} by itself would represent. 336 337A 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 347or backward. The effects of relative items accumulate. Here are some 348examples: 349 350@example 3511 year 3521 year ago 3533 years 3542 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} 364The unit of time displacement may be selected by the string @samp{year} 365or @samp{month} for moving by whole years or months. These are fuzzy 366units, as years and months are not all of equal duration. More precise 367units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 368days, @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 371accepted and ignored. 372 373@findex ago @r{in date strings} 374The unit of time may be preceded by a multiplier, given as an optionally 375signed number. Unsigned numbers are taken as positively signed. No 376number at all implies 1 for a multiplier. Following a relative item by 377the string @samp{ago} is equivalent to preceding the unit by a 378multiplier 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} 383The string @samp{tomorrow} is worth one day in the future (equivalent 384to @samp{day}), the string @samp{yesterday} is worth 385one 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} 390The strings @samp{now} or @samp{today} are relative items corresponding 391to zero-valued time displacement, these strings come from the fact 392a zero-valued time displacement represents the current time when not 393otherwise changed by previous items. They may be used to stress other 394items, like in @samp{12:00 today}. The string @samp{this} also has 395the meaning of a zero-valued time displacement, but is preferred in 396date strings like @samp{this thursday}. 397 398When a relative item causes the resulting date to cross a boundary 399where the clocks were adjusted, typically for daylight saving time, 400the resulting date and time are adjusted accordingly. 401 402The fuzz in units can cause problems with relative items. For 403example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, 404because 2003-06-31 is an invalid date. To determine the previous 405month more reliably, you can ask for the month before the 15th of the 406current month. For example: 407 408@example 409$ date -R 410Thu, 31 Jul 2003 13:02:39 -0700 411$ date --date='-1 month' +'Last month was %B?' 412Last month was July? 413$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 414Last month was June! 415@end example 416 417Also, take care when manipulating dates around clock changes such as 418daylight saving leaps. In a few cases these have added or subtracted 419as much as 24 hours from the clock, so it is often wise to adopt 420universal 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 428The precise interpretation of a pure decimal number depends 429on the context in the date string. 430 431If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 432other calendar date item (@pxref{Calendar date items}) appears before it 433in the date string, then @var{yyyy} is read as the year, @var{mm} as the 434month number and @var{dd} as the day of the month, for the specified 435calendar date. 436 437If the decimal number is of the form @var{hh}@var{mm} and no other time 438of day item appears before it in the date string, then @var{hh} is read 439as the hour of the day and @var{mm} as the minute of the hour, for the 440specified time of day. @var{mm} can also be omitted. 441 442If both a calendar date and a time of day appear to the left of a number 443in the date string, but no relative item, then the number overrides the 444year. 445 446 447@node Seconds since the Epoch 448@appendixsubsec Seconds since the Epoch 449 450If you precede a number with @samp{@@}, it represents an internal time 451stamp as a count of seconds. The number can contain an internal 452decimal point (either @samp{.} or @samp{,}); any excess precision not 453supported by the internal representation is truncated toward minus 454infinity. Such a number cannot be combined with any other date 455item, as it specifies a complete time stamp. 456 457@cindex beginning of time, for @acronym{POSIX} 458@cindex epoch, for @acronym{POSIX} 459Internally, computer times are represented as a count of seconds since 460an 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 46300:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other 464@acronym{POSIX}-compliant systems support such times as an extension 465to @acronym{POSIX}, using negative counts, so that @samp{@@-1} 466represents 1969-12-31 23:59:59 @sc{utc}. 467 468Traditional Unix systems count seconds with 32-bit two's-complement 469integers and can represent times from 1901-12-13 20:45:52 through 4702038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts 471of seconds with nanosecond subcounts, and can represent all the times 472in the known lifetime of the universe to a resolution of 1 nanosecond. 473 474On most systems, these counts ignore the presence of leap seconds. 475For example, on most systems @samp{@@915148799} represents 1998-12-31 47623: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 4781998-12-31 23:59:60 @sc{utc}. 479 480@node Specifying time zone rules 481@appendixsubsec Specifying time zone rules 482 483@vindex TZ 484Normally, dates are interpreted using the rules of the current time 485zone, which in turn are specified by the @env{TZ} environment 486variable, or by a system default if @env{TZ} is not set. To specify a 487different set of default time zone rules that apply just to one date, 488start the date with a string of the form @samp{TZ="@var{rule}"}. The 489two quote characters (@samp{"}) must be present in the date, and any 490quotes or backslashes within @var{rule} must be escaped by a 491backslash. 492 493For example, with the @acronym{GNU} @command{date} command you can 494answer the question ``What time is it in New York when a Paris clock 495shows 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' 501Sun Oct 31 01:30:00 EDT 2004 502@end example 503 504In this example, the @option{--date} operand begins with its own 505@env{TZ} setting, so the rest of that operand is processed according 506to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 50706: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 509rules, it uses New York time. (Paris was normally six hours ahead of 510New York in 2004, but this example refers to a brief Halloween period 511when the gap was five hours.) 512 513A @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}. 515A recent catalog of location names appears in the 516@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time 517Gateway}. A few non-@acronym{GNU} hosts require a colon before a 518location name in a @env{TZ} setting, e.g., 519@samp{TZ=":America/New_York"}. 520 521The @samp{tz} database includes a wide variety of locations ranging 522from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but 523if you are at sea and have your own private time zone, or if you are 524using a non-@acronym{GNU} host that does not support the @samp{tz} 525database, you may need to use a @acronym{POSIX} rule instead. Simple 526@acronym{POSIX} rules like @samp{UTC0} specify a time zone without 527daylight saving time; other rules can specify simple daylight saving 528regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, 529libc, 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 544at Chapel Hill. The code was later tweaked by a couple of people on 545Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 546and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 547revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, 548Paul Eggert and others. 549 550@cindex Pinard, F. 551@cindex Berry, K. 552This chapter was originally produced by Fran@,{c}ois Pinard 553(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, 554and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). 555