1@c GNU date syntax documentation 2@c $MirOS: src/gnu/usr.bin/cvs/doc/getdate.texi,v 1.7 2010/09/19 19:42:56 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 25First, a quote: 26 27@quotation 28Our units of temporal measurement, from seconds on up to months, are so 29complicated, asymmetrical and disjunctive so as to make coherent mental 30reckoning in time all but impossible. Indeed, had some tyrannical god 31contrived to enslave our minds to time, to make it all but impossible 32for us to escape subjection to sodden routines and unpleasant surprises, 33he could hardly have done better than handing down our present system. 34It is like a set of trapezoidal building blocks, with no vertical or 35horizontal surfaces, like a language in which the simplest thought 36demands ornate constructions, useless particles and lengthy 37circumlocutions. Unlike the more successful patterns of language and 38science, which enable us to face experience boldly or at least 39level-headedly, our system of temporal calculation silently and 40persistently encourages our terror of time. 41 42@dots{} It is as though architects had to measure length in feet, width 43in meters and height in ells; as though basic instruction manuals 44demanded a knowledge of five different languages. It is no wonder then 45that we often look into our own immediate past or future, last Tuesday 46or 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 51This section describes the textual date representations that @sc{gnu} 52programs accept. These are the strings you, as a user, can supply as 53arguments 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 75A @dfn{date} is a string, possibly empty, containing many items 76separated by whitespace. The whitespace may be omitted when no 77ambiguity arises. The empty string means the beginning of today (i.e., 78midnight). Order of the items is immaterial. A date string may contain 79many 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} 97A few ordinal numbers may be written out in words in some contexts. This is 98most useful for specifying day of the week items or relative items (see 99below). 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 103ordinal 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 110When a month is written this way, it is still considered to be written 111numerically, instead of being ``spelled in full''; this changes the 112allowed strings. 113 114@cindex language, in dates 115In the current implementation, only English is supported for words and 116abbreviations 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 121The output of @command{date} is not always acceptable as a date string, 122not only because of the language problem, but also because there is no 123standard meaning for time zone items like @samp{IST}. When using 124@command{date} to generate a date string intended to be parsed later, 125specify a date format that is independent of language and that does not 126use time zone items other than @samp{UTC} and @samp{Z}. Here are some 127ways to do this: 128 129@example 130$ LC_ALL=C TZ=UTC0 date 131Fri Dec 15 19:48:05 UTC 2000 132$ TZ=UTC0 date +"%Y-%m-%d %H:%M:%SZ" 1332000-12-15 19:48:05Z 134$ date --iso-8601=seconds # a GNU extension 1352000-12-15T11:48:05-0800 136$ date --iso-8601=ns # a GNU extension 1372004-02-29T16:21:42,692722128-0800 138$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 1392004-02-29 16:21:42,692722128-0800 140$ date --rfc-2822 # a GNU extension 141Fri, 15 Dec 2000 11:48:05 -0800 142$ date +"%Y-%m-%d %H:%M:%S %z" # %z is a GNU extension. 1432000-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 152Alphabetic case is completely ignored in dates. Comments may be introduced 153between round parentheses, as long as included parentheses are properly 154nested. Hyphens not followed by a digit are currently ignored. Leading 155zeros on numbers are ignored. 156 157 158@node Calendar date items 159@section Calendar date items 160 161@cindex calendar date item 162 163A @dfn{calendar date item} specifies a day of the year. It is 164specified differently, depending on whether the month is specified 165numerically or literally. All these strings specify the same calendar date: 166 167@example 1681972-09-24 # @sc{iso} 8601. 16972-9-24 # Assume 19xx for 69 through 99, 170 # 20xx for 00 through 68. 17172-09-24 # Leading zeros are ignored. 1729/24/72 # Common U.S. writing. 17324 September 1972 17424 Sept 72 # September has a special abbreviation. 17524 Sep 72 # Three-letter abbreviations always allowed. 176Sep 24, 1972 17724-sep-72 17824sep72 179@end example 180 181The year can also be omitted. In this case, the last specified year is 182used, or the current year if none. For example: 183 184@example 1859/24 186sep 24 187@end example 188 189Here are the rules. 190 191@cindex @sc{iso} 8601 date format 192@cindex date format, @sc{iso} 8601 193For numeric months, the @sc{iso} 8601 format 194@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is 195any 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 197if a number is less than ten. If @var{year} is 68 or smaller, then 2000 198is added to it; otherwise, if @var{year} is less than 100, 199then 1900 is added to it. The construct 200@samp{@var{month}/@var{day}/@var{year}}, popular in the United States, 201is accepted. Also @samp{@var{month}/@var{day}}, omitting the year. 202 203@cindex month names in date strings 204@cindex abbreviations for months 205Literal 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 209to their first three letters, possibly followed by an abbreviating dot. 210It is also permitted to write @samp{Sept} instead of @samp{September}. 211 212When months are written literally, the calendar date may be given as any 213of 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 222Or, 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 234A @dfn{time of day item} in date strings specifies the time on a given 235day. Here are some examples, all of which represent the same time: 236 237@example 23820:02:00.000000 23920:02 2408:02pm 24120:02-0500 # In @sc{est} (U.S. Eastern Standard Time). 242@end example 243 244More generally, the time of the day may be given as 245@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is 246a number between 0 and 23, @var{minute} is a number between 0 and 24759, and @var{second} is a number between 0 and 59, with an optional 248fraction separated by @samp{.} or @samp{,} consisting of digits. 249Alternatively, @samp{:@var{second}} can be omitted, in which case 250it 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} 256If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.} 257or @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} 259indicates the first half of the day, @samp{pm} indicates the second 260half of the day. In this notation, 12 is the predecessor of 1: 261midnight is @samp{12am} while noon is @samp{12pm}. 262(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm}, 263as opposed to the old tradition derived from Latin 264which uses @samp{12m} for noon and @samp{12pm} for midnight.) 265 266@cindex time zone correction 267@cindex minutes, time zone correction by 268The time may alternatively be followed by a time zone correction, 269expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+} 270or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number 271of zone minutes. You 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). The @var{minute} 278part of the time of day may not be elided when a time zone correction 279is used. This is the best way to specify a time zone correction by 280fractional parts of an hour. 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 313 314@node Day of week items 315@section Day of week items 316 317@cindex day of week item 318 319The 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 322Days 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 325first three letters, optionally followed by a period. The special 326abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for 327@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are 328also allowed. 329 330@findex next @var{day} 331@findex last @var{day} 332A number may precede a day of the week item to move forward 333supplementary weeks. It is best used in expression like @samp{third 334monday}. In this context, @samp{last @var{day}} or @samp{next 335@var{day}} is also acceptable; they move one week before or after 336the day that @var{day} by itself would represent. 337 338A 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 348or backward. The effects of relative items accumulate. Here are some 349examples: 350 351@example 3521 year 3531 year ago 3543 years 3552 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} 365The unit of time displacement may be selected by the string @samp{year} 366or @samp{month} for moving by whole years or months. These are fuzzy 367units, as years and months are not all of equal duration. More precise 368units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7 369days, @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 372accepted and ignored. 373 374@findex ago @r{in date strings} 375The unit of time may be preceded by a multiplier, given as an optionally 376signed number. Unsigned numbers are taken as positively signed. No 377number at all implies 1 for a multiplier. Following a relative item by 378the string @samp{ago} is equivalent to preceding the unit by a 379multiplier 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} 384The string @samp{tomorrow} is worth one day in the future (equivalent 385to @samp{day}), the string @samp{yesterday} is worth 386one 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} 391The strings @samp{now} or @samp{today} are relative items corresponding 392to zero-valued time displacement, these strings come from the fact 393a zero-valued time displacement represents the current time when not 394otherwise changed by previous items. They may be used to stress other 395items, like in @samp{12:00 today}. The string @samp{this} also has 396the meaning of a zero-valued time displacement, but is preferred in 397date strings like @samp{this thursday}. 398 399When a relative item causes the resulting date to cross a boundary 400where the clocks were adjusted, typically for daylight-saving time, 401the resulting date and time are adjusted accordingly. 402 403The fuzz in units can cause problems with relative items. For 404example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01, 405because 2003-06-31 is an invalid date. To determine the previous 406month more reliably, you can ask for the month before the 15th of the 407current month. For example: 408 409@example 410$ date -R 411Thu, 31 Jul 2003 13:02:39 -0700 412$ date --date="-1 month" +'Last month was %B?' 413Last month was July? 414$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' 415Last month was June! 416@end example 417 418Also, take care when manipulating dates around clock changes such as 419daylight saving leaps. In a few cases these have added or subtracted 420as much as 24 hours from the clock, so it is often wise to adopt 421universal 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 429The precise interpretation of a pure decimal number depends 430on the context in the date string. 431 432If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no 433other calendar date item (@pxref{Calendar date items}) appears before it 434in the date string, then @var{yyyy} is read as the year, @var{mm} as the 435month number and @var{dd} as the day of the month, for the specified 436calendar date. 437 438If the decimal number is of the form @var{hh}@var{mm} and no other time 439of day item appears before it in the date string, then @var{hh} is read 440as the hour of the day and @var{mm} as the minute of the hour, for the 441specified time of the day. @var{mm} can also be omitted. 442 443If both a calendar date and a time of day appear to the left of a number 444in the date string, but no relative item, then the number overrides the 445year. 446 447 448@node Seconds since the Epoch 449@section Seconds since the Epoch 450 451If you give a string consisting of @samp{@@} followed by a decimal 452number, it is parsed as an internal time stamp, @sc{utc} for 453@acronym{POSIX} compliant systems, @sc{tai} for systems which keep 454time correctly, and directly mapped to a kernel time. The implementation 455handles an optional fraction separated by @samp{.} or @samp{,} and 456truncates to a supported internal precision, rounding towards the 457negative infinity. Since the kernel time stamp represents complete 458date and time information, it cannot be combined with any other 459format given. 460 461@cindex beginning of time, for @acronym{POSIX} 462@cindex epoch, for @acronym{POSIX} 463Although the date syntax here can represent any possible time since the 464year zero, computer integers often cannot represent such a wide range of 465time. 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 468traditional Unix systems have 32-bit signed @code{time_t} and can represent 469times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 @sc{utc}, such 470that @samp{@@0} represents the epoch, @samp{@@1} represents 1970-01-01 47100: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 47364-bit signed @code{time_t} can represent all the times in the known 474lifetime of the universe. Modern @acronym{UNIX} systems also can give 475precise timecounters in the nanosecond or even attosecond range with 476a resolution often only a small multiply, like 10000, of the CPU 477frequency (on fast machines). 478 479@acronym{POSIX} conformant systems do not count leap seconds, and their 480kernel time is a seconds-since-epoch representation of @sc{utc} (which 481is a calendar time); the MirOS family of operating systems keeps time 482as seconds since the epoch, @sc{tai}, correctly counting leap seconds 483and providing conversion functions. Most MirOS ports have already 484switched to a 64-bit signed @code{time_t}, some are using a 485@sc{djb}-compatible @code{tai_t} internally. The rest of this 486document has not been throughoutly checked for @sc{utc} vs @sc{tai} 487correctness. For @acronym{POSIX}ly broken systems, @samp{@@915148799} 488represents 1998-12-31 23:59:59 @sc{utc}, @samp{@@915148800} represents 4891999-01-01 00:00:00 @sc{utc}, and there is no way to represent the 490intervening leap second 1998-12-31 23:59:60 @sc{utc}. Also, calculation 491of time deltas is wrong, such as the age of the MirOS founder is already 492off 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 508at Chapel Hill. The code was later tweaked by a couple of people on 509Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com}) 510and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various 511revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering, 512Paul Eggert and others. 513 514@cindex Pinard, F. 515@cindex Berry, K. 516This chapter was originally produced by Fran@,{c}ois Pinard 517(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code, 518and then edited by K.@: Berry (@email{kb@@cs.umb.edu}). 519 520The version of this chapter you are reading comes with CVS 1.12 and 521the MirOS family of operating systems; it is based upon an older 522version of the @acronym{GNU} coreutils manual which is not yet 523restricted by the licencing conditions of the GNU Free Documentation 524License, but more freely redistributable. Appropriate changes for 525the in-tree @code{get_date} version of CVS have been applied. 526The MirOS version is maintained by Thorsten Glaser @email{tg@@mirbsd.de}. 527