162321Salfred@c GNU date syntax documentation 262321Salfred 362321Salfred@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 462321Salfred@c 2004, 2005, 2006, 2009, 2010 Free Software Foundation, Inc. 562321Salfred 662321Salfred@c Permission is granted to copy, distribute and/or modify this document 762321Salfred@c under the terms of the GNU Free Documentation License, Version 1.3 or 862321Salfred@c any later version published by the Free Software Foundation; with no 962321Salfred@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 1062321Salfred@c Texts. A copy of the license is included in the ``GNU Free 1162321Salfred@c Documentation License'' file as part of this distribution. 1262321Salfred 1362321Salfred@node Date input formats 1462321Salfred@chapter Date input formats 1592986Sobrien 1662321Salfred@cindex date input formats 1762321Salfred@findex get_date 1862321Salfred 1992986SobrienFirst, a quote: 2092986Sobrien 2162321Salfred@quotation 2262321SalfredOur units of temporal measurement, from seconds on up to months, are so 2362321Salfredcomplicated, asymmetrical and disjunctive so as to make coherent mental 2462321Salfredreckoning in time all but impossible. Indeed, had some tyrannical god 2562321Salfredcontrived to enslave our minds to time, to make it all but impossible 2692941Sobrienfor us to escape subjection to sodden routines and unpleasant surprises, 2792941Sobrienhe could hardly have done better than handing down our present system. 2862321SalfredIt is like a set of trapezoidal building blocks, with no vertical or 2962321Salfredhorizontal surfaces, like a language in which the simplest thought 3062321Salfreddemands ornate constructions, useless particles and lengthy 3162321Salfredcircumlocutions. Unlike the more successful patterns of language and 3262321Salfredscience, which enable us to face experience boldly or at least 3392905Sobrienlevel-headedly, our system of temporal calculation silently and 3462321Salfredpersistently encourages our terror of time. 3562321Salfred 3662321Salfred@dots{} It is as though architects had to measure length in feet, width 3762321Salfredin meters and height in ells; as though basic instruction manuals 3862321Salfreddemanded a knowledge of five different languages. It is no wonder then 3962321Salfredthat we often look into our own immediate past or future, last Tuesday 4062321Salfredor a week from Sunday, with feelings of helpless confusion. @dots{} 4162321Salfred 4262321Salfred--- Robert Grudin, @cite{Time and the Art of Living}. 4362321Salfred@end quotation 4462321Salfred 4562321SalfredThis section describes the textual date representations that @sc{gnu} 4662321Salfredprograms accept. These are the strings you, as a user, can supply as 4762321Salfredarguments to the various programs. The C interface (via the 4862321Salfred@code{get_date} function) is not described here. 4962321Salfred 5062321Salfred@menu 5162321Salfred* General date syntax:: Common rules. 5262321Salfred* Calendar date items:: 19 Dec 1994. 5362321Salfred* Time of day items:: 9:20pm. 5492905Sobrien* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. 5562321Salfred* Day of week items:: Monday and others. 5662321Salfred* Relative items in date strings:: next tuesday, 2 years ago. 5762321Salfred* Pure numbers in date strings:: 19931219, 1440. 5862321Salfred* Seconds since the Epoch:: @@1078100502. 59* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". 60* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al. 61@end menu 62 63 64@node General date syntax 65@section General date syntax 66 67@cindex general date syntax 68 69@cindex items in date strings 70A @dfn{date} is a string, possibly empty, containing many items 71separated by whitespace. The whitespace may be omitted when no 72ambiguity arises. The empty string means the beginning of today (i.e., 73midnight). Order of the items is immaterial. A date string may contain 74many flavors of items: 75 76@itemize @bullet 77@item calendar date items 78@item time of day items 79@item time zone items 80@item day of the week items 81@item relative items 82@item pure numbers. 83@end itemize 84 85@noindent We describe each of these item types in turn, below. 86 87@cindex numbers, written-out 88@cindex ordinal numbers 89@findex first @r{in date strings} 90@findex next @r{in date strings} 91@findex last @r{in date strings} 92A few ordinal numbers may be written out in words in some contexts. This is 93most useful for specifying day of the week items or relative items (see 94below). Among the most commonly used ordinal numbers, the word 95@samp{last} stands for @math{-1}, @samp{this} stands for 0, and 96@samp{first} and @samp{next} both stand for 1. Because the word 97@samp{second} stands for the unit of time there is no way to write the 98ordinal number 2, but for convenience @samp{third} stands for 3, 99@samp{fourth} for 4, @samp{fifth} for 5, 100@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8, 101@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and 102@samp{twelfth} for 12. 103 104@cindex months, written-out 105When a month is written this way, it is still considered to be written 106numerically, instead of being ``spelled in full''; this changes the 107allowed strings. 108 109@cindex language, in dates 110In the current implementation, only English is supported for words and 111abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first}, 112@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}. 113 114@cindex language, in dates 115@cindex time zone item 116The output of the @command{date} command 117is not always acceptable as a date string, 118not only because of the language problem, but also because there is no 119standard meaning for time zone items like @samp{IST}. When using 120@command{date} to generate a date string intended to be parsed later, 121specify a date format that is independent of language and that does not 122use time zone items other than @samp{UTC} and @samp{Z}. Here are some 123ways to do this: 124 125@example 126$ LC_ALL=C TZ=UTC0 date 127Mon Mar 1 00:21:42 UTC 2004 128$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 1292004-03-01 00:21:42Z 130$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 1312004-02-29 16:21:42,692722128-0800 132$ date --rfc-2822 # a GNU extension 133Sun, 29 Feb 2004 16:21:42 -0800 134$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 1352004-02-29 16:21:42 -0800 136$ date +'@@%s.%N' # %s and %N are GNU extensions. 137@@1078100502.692722128 138@end example 139 140@cindex case, ignored in dates 141@cindex comments, in dates 142Alphabetic case is completely ignored in dates. Comments may be introduced 143between round parentheses, as long as included parentheses are properly 144nested. Hyphens not followed by a digit are currently ignored. Leading 145zeros on numbers are ignored. 146 147Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are 148rejected. In the typical case of a host that does not support leap 149seconds, a time like @samp{23:59:60} is rejected even if it 150corresponds to a valid leap second. 151 152 153@node Calendar date items 154@section Calendar date items 155 156@cindex calendar date item 157 158A @dfn{calendar date item} specifies a day of the year. It is 159specified differently, depending on whether the month is specified 160numerically or literally. All these strings specify the same calendar date: 161 162@example 1631972-09-24 # @sc{iso} 8601. 16472-9-24 # Assume 19xx for 69 through 99, 165 # 20xx for 00 through 68. 16672-09-24 # Leading zeros are ignored. 1679/24/72 # Common U.S. writing. 16824 September 1972 16924 Sept 72 # September has a special abbreviation. 17024 Sep 72 # Three-letter abbreviations always allowed. 171Sep 24, 1972 17224-sep-72 17324sep72 174@end example 175 176The year can also be omitted. In this case, the last specified year is 177used, or the current year if none. For example: 178 179@example 1809/24 181sep 24 182@end example 183 184Here are the rules. 185 186@cindex @sc{iso} 8601 date format 187@cindex date format, @sc{iso} 8601 188For numeric months, the @sc{iso} 8601 format 189@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 190any positive number, @var{month} is a number between 01 and 12, and 191@var{day} is a number between 01 and 31. A leading zero must be present 192if a number is less than ten. If @var{year} is 68 or smaller, then 2000 193is added to it; otherwise, if @var{year} is less than 100, 194then 1900 is added to it. The construct 195@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 196is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 197 198@cindex month names in date strings 199@cindex abbreviations for months 200Literal months may be spelled out in full: @samp{January}, 201@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June}, 202@samp{July}, @samp{August}, @samp{September}, @samp{October}, 203@samp{November} or @samp{December}. Literal months may be abbreviated 204to their first three letters, possibly followed by an abbreviating dot. 205It is also permitted to write @samp{Sept} instead of @samp{September}. 206 207When months are written literally, the calendar date may be given as any 208of the following: 209 210@example 211@var{day} @var{month} @var{year} 212@var{day} @var{month} 213@var{month} @var{day} @var{year} 214@var{day}-@var{month}-@var{year} 215@end example 216 217Or, omitting the year: 218 219@example 220@var{month} @var{day} 221@end example 222 223 224@node Time of day items 225@section Time of day items 226 227@cindex time of day item 228 229A @dfn{time of day item} in date strings specifies the time on a given 230day. Here are some examples, all of which represent the same time: 231 232@example 23320:02:00.000000 23420:02 2358:02pm 23620:02-0500 # In @sc{est} (U.S. Eastern Standard Time). 237@end example 238 239More generally, the time of day may be given as 240@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is 241a number between 0 and 23, @var{minute} is a number between 0 and 24259, and @var{second} is a number between 0 and 59 possibly followed by 243@samp{.} or @samp{,} and a fraction containing one or more digits. 244Alternatively, 245@samp{:@var{second}} can be omitted, in which case it is taken to 246be zero. On the rare hosts that support leap seconds, @var{second} 247may be 60. 248 249@findex am @r{in date strings} 250@findex pm @r{in date strings} 251@findex midnight @r{in date strings} 252@findex noon @r{in date strings} 253If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} 254or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and 255@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am} 256indicates the first half of the day, @samp{pm} indicates the second 257half of the day. In this notation, 12 is the predecessor of 1: 258midnight is @samp{12am} while noon is @samp{12pm}. 259(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, 260as opposed to the old tradition derived from Latin 261which uses @samp{12m} for noon and @samp{12pm} for midnight.) 262 263@cindex time zone correction 264@cindex minutes, time zone correction by 265The time may alternatively be followed by a time zone correction, 266expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} 267or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number 268of zone minutes. 269The zone minutes term, @var{mm}, may be omitted, in which case 270the one- or two-digit correction is interpreted as a number of hours. 271You can also separate @var{hh} from @var{mm} with a colon. 272When a time zone correction is given this way, it 273forces interpretation of the time relative to 274Coordinated Universal Time (@sc{utc}), overriding any previous 275specification 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 277ahead of @sc{utc} (e.g., India). 278This is the best way to 279specify a time zone correction by fractional parts of an hour. 280The maximum zone correction is 24 hours. 281 282Either @samp{am}/@samp{pm} or a time zone correction may be specified, 283but not both. 284 285 286@node Time zone items 287@section Time zone items 288 289@cindex time zone item 290 291A @dfn{time zone item} specifies an international time zone, indicated 292by a small set of letters, e.g., @samp{UTC} or @samp{Z} 293for Coordinated Universal 294Time. Any included periods are ignored. By following a 295non-daylight-saving time zone by the string @samp{DST} in a separate 296word (that is, separated by some white space), the corresponding 297daylight saving time zone may be specified. 298Alternatively, a non-daylight-saving time zone can be followed by a 299time zone correction, to add the two values. This is normally done 300only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to 301@samp{+05:30}. 302 303Time zone items other than @samp{UTC} and @samp{Z} 304are obsolescent and are not recommended, because they 305are ambiguous; for example, @samp{EST} has a different meaning in 306Australia than in the United States. Instead, it's better to use 307unambiguous numeric time zone corrections like @samp{-0500}, as 308described in the previous section. 309 310If neither a time zone item nor a time zone correction is supplied, 311time stamps are interpreted using the rules of the default time zone 312(@pxref{Specifying time zone rules}). 313 314 315@node Day of week items 316@section Day of week items 317 318@cindex day of week item 319 320The explicit mention of a day of the week will forward the date 321(only if necessary) to reach that day of the week in the future. 322 323Days of the week may be spelled out in full: @samp{Sunday}, 324@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday}, 325@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their 326first three letters, optionally followed by a period. The special 327abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 328@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 329also allowed. 330 331@findex next @var{day} 332@findex last @var{day} 333A number may precede a day of the week item to move forward 334supplementary weeks. It is best used in expression like @samp{third 335monday}. In this context, @samp{last @var{day}} or @samp{next 336@var{day}} is also acceptable; they move one week before or after 337the day that @var{day} by itself would represent. 338 339A comma following a day of the week item is ignored. 340 341 342@node Relative items in date strings 343@section Relative items in date strings 344 345@cindex relative items in date strings 346@cindex displacement of dates 347 348@dfn{Relative items} adjust a date (or the current date if none) forward 349or backward. The effects of relative items accumulate. Here are some 350examples: 351 352@example 3531 year 3541 year ago 3553 years 3562 days 357@end example 358 359@findex year @r{in date strings} 360@findex month @r{in date strings} 361@findex fortnight @r{in date strings} 362@findex week @r{in date strings} 363@findex day @r{in date strings} 364@findex hour @r{in date strings} 365@findex minute @r{in date strings} 366The unit of time displacement may be selected by the string @samp{year} 367or @samp{month} for moving by whole years or months. These are fuzzy 368units, as years and months are not all of equal duration. More precise 369units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 370days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes, 371@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or 372@samp{sec} worth one second. An @samp{s} suffix on these units is 373accepted and ignored. 374 375@findex ago @r{in date strings} 376The unit of time may be preceded by a multiplier, given as an optionally 377signed number. Unsigned numbers are taken as positively signed. No 378number at all implies 1 for a multiplier. Following a relative item by 379the string @samp{ago} is equivalent to preceding the unit by a 380multiplier with value @math{-1}. 381 382@findex day @r{in date strings} 383@findex tomorrow @r{in date strings} 384@findex yesterday @r{in date strings} 385The string @samp{tomorrow} is worth one day in the future (equivalent 386to @samp{day}), the string @samp{yesterday} is worth 387one day in the past (equivalent to @samp{day ago}). 388 389@findex now @r{in date strings} 390@findex today @r{in date strings} 391@findex this @r{in date strings} 392The strings @samp{now} or @samp{today} are relative items corresponding 393to zero-valued time displacement, these strings come from the fact 394a zero-valued time displacement represents the current time when not 395otherwise changed by previous items. They may be used to stress other 396items, like in @samp{12:00 today}. The string @samp{this} also has 397the meaning of a zero-valued time displacement, but is preferred in 398date strings like @samp{this thursday}. 399 400When a relative item causes the resulting date to cross a boundary 401where the clocks were adjusted, typically for daylight saving time, 402the resulting date and time are adjusted accordingly. 403 404The fuzz in units can cause problems with relative items. For 405example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, 406because 2003-06-31 is an invalid date. To determine the previous 407month more reliably, you can ask for the month before the 15th of the 408current month. For example: 409 410@example 411$ date -R 412Thu, 31 Jul 2003 13:02:39 -0700 413$ date --date='-1 month' +'Last month was %B?' 414Last month was July? 415$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 416Last month was June! 417@end example 418 419Also, take care when manipulating dates around clock changes such as 420daylight saving leaps. In a few cases these have added or subtracted 421as much as 24 hours from the clock, so it is often wise to adopt 422universal time by setting the @env{TZ} environment variable to 423@samp{UTC0} before embarking on calendrical calculations. 424 425@node Pure numbers in date strings 426@section Pure numbers in date strings 427 428@cindex pure numbers in date strings 429 430The precise interpretation of a pure decimal number depends 431on the context in the date string. 432 433If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 434other calendar date item (@pxref{Calendar date items}) appears before it 435in the date string, then @var{yyyy} is read as the year, @var{mm} as the 436month number and @var{dd} as the day of the month, for the specified 437calendar date. 438 439If the decimal number is of the form @var{hh}@var{mm} and no other time 440of day item appears before it in the date string, then @var{hh} is read 441as the hour of the day and @var{mm} as the minute of the hour, for the 442specified time of day. @var{mm} can also be omitted. 443 444If both a calendar date and a time of day appear to the left of a number 445in the date string, but no relative item, then the number overrides the 446year. 447 448 449@node Seconds since the Epoch 450@section Seconds since the Epoch 451 452If you precede a number with @samp{@@}, it represents an internal time 453stamp as a count of seconds. The number can contain an internal 454decimal point (either @samp{.} or @samp{,}); any excess precision not 455supported by the internal representation is truncated toward minus 456infinity. Such a number cannot be combined with any other date 457item, as it specifies a complete time stamp. 458 459@cindex beginning of time, for @acronym{POSIX} 460@cindex epoch, for @acronym{POSIX} 461Internally, computer times are represented as a count of seconds since 462an epoch---a well-defined point of time. On @acronym{GNU} and 463@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so 464@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01 46500:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other 466@acronym{POSIX}-compliant systems support such times as an extension 467to @acronym{POSIX}, using negative counts, so that @samp{@@-1} 468represents 1969-12-31 23:59:59 @sc{utc}. 469 470Traditional Unix systems count seconds with 32-bit two's-complement 471integers and can represent times from 1901-12-13 20:45:52 through 4722038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts 473of seconds with nanosecond subcounts, and can represent all the times 474in the known lifetime of the universe to a resolution of 1 nanosecond. 475 476On most hosts, these counts ignore the presence of leap seconds. 477For example, on most hosts @samp{@@915148799} represents 1998-12-31 47823:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00 479@sc{utc}, and there is no way to represent the intervening leap second 4801998-12-31 23:59:60 @sc{utc}. 481 482@node Specifying time zone rules 483@section Specifying time zone rules 484 485@vindex TZ 486Normally, dates are interpreted using the rules of the current time 487zone, which in turn are specified by the @env{TZ} environment 488variable, or by a system default if @env{TZ} is not set. To specify a 489different set of default time zone rules that apply just to one date, 490start the date with a string of the form @samp{TZ="@var{rule}"}. The 491two quote characters (@samp{"}) must be present in the date, and any 492quotes or backslashes within @var{rule} must be escaped by a 493backslash. 494 495For example, with the @acronym{GNU} @command{date} command you can 496answer the question ``What time is it in New York when a Paris clock 497shows 6:30am on October 31, 2004?'' by using a date beginning with 498@samp{TZ="Europe/Paris"} as shown in the following shell transcript: 499 500@example 501$ export TZ="America/New_York" 502$ date --date='TZ="Europe/Paris" 2004-10-31 06:30' 503Sun Oct 31 01:30:00 EDT 2004 504@end example 505 506In this example, the @option{--date} operand begins with its own 507@env{TZ} setting, so the rest of that operand is processed according 508to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31 50906:30} as if it were in Paris. However, since the output of the 510@command{date} command is processed according to the overall time zone 511rules, it uses New York time. (Paris was normally six hours ahead of 512New York in 2004, but this example refers to a brief Halloween period 513when the gap was five hours.) 514 515A @env{TZ} value is a rule that typically names a location in the 516@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}. 517A recent catalog of location names appears in the 518@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time 519Gateway}. A few non-@acronym{GNU} hosts require a colon before a 520location name in a @env{TZ} setting, e.g., 521@samp{TZ=":America/New_York"}. 522 523The @samp{tz} database includes a wide variety of locations ranging 524from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but 525if you are at sea and have your own private time zone, or if you are 526using a non-@acronym{GNU} host that does not support the @samp{tz} 527database, you may need to use a @acronym{POSIX} rule instead. Simple 528@acronym{POSIX} rules like @samp{UTC0} specify a time zone without 529daylight saving time; other rules can specify simple daylight saving 530regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ}, 531libc, The GNU C Library}. 532 533@node Authors of get_date 534@section Authors of @code{get_date} 535 536@cindex authors of @code{get_date} 537 538@cindex Bellovin, Steven M. 539@cindex Salz, Rich 540@cindex Berets, Jim 541@cindex MacKenzie, David 542@cindex Meyering, Jim 543@cindex Eggert, Paul 544@code{get_date} was originally implemented by Steven M. Bellovin 545(@email{smb@@research.att.com}) while at the University of North Carolina 546at Chapel Hill. The code was later tweaked by a couple of people on 547Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 548and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 549revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, 550Paul Eggert and others. 551 552@cindex Pinard, F. 553@cindex Berry, K. 554This chapter was originally produced by Fran@,{c}ois Pinard 555(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, 556and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). 557