1.\" $NetBSD: parsedate.3,v 1.24 2017/03/22 18:17:42 kre Exp $ 2.\" 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 22, 2017 31.Dt PARSEDATE 3 32.Os 33.Sh NAME 34.Nm parsedate 35.Nd date parsing function 36.Sh LIBRARY 37.Lb libutil 38.Sh SYNOPSIS 39.In util.h 40.Ft time_t 41.Fn parsedate "const char *datestr" "const time_t *time" "const int *tzoff" 42.Sh DESCRIPTION 43The 44.Fn parsedate 45function parses a datetime from 46.Ar datestr 47described in English relative to an optional 48.Ar time 49point, 50and an optional timezone offset (in minutes behind/west of UTC) 51specified in 52.Ar tzoff . 53If 54.Ar time 55is 56.Dv NULL 57then the current time is used. 58If 59.Ar tzoff 60is 61.Dv NULL , 62then the current time zone is used. 63.Pp 64The 65.Ar datestr 66is a sequence of white-space separated items. 67The white-space is optional if the concatenated items are not ambiguous. 68An empty 69.Ar datestr 70is equivalent to midnight today (the beginning of this day). 71.Pp 72The following words have the indicated numeric meanings: 73.Dv last = 74\-1, 75.Dv this = 760, 77.Dv first , next , 78or 79.Dv one = 801, 81.Dv second 82is unused so that it is not confused with 83.Dq seconds , 84.Dv two = 852, 86.Dv third 87or 88.Dv three = 893, 90.Dv fourth 91or 92.Dv four = 934, 94.Dv fifth 95or 96.Dv five = 975, 98.Dv sixth 99or 100.Dv six = 1016, 102.Dv seventh 103or 104.Dv seven = 1057, 106.Dv eighth 107or 108.Dv eight = 1098, 110.Dv ninth 111or 112.Dv nine = 1139, 114.Dv tenth 115or 116.Dv ten = 11710, 118.Dv eleventh 119or 120.Dv eleven = 12111, 122.Dv twelfth 123or 124.Dv twelve = 12512. 126.Pp 127The following words are recognized in English only: 128.Dv AM , 129.Dv PM , 130.Dv a.m. , 131.Dv p.m. , 132.Dv midnight , 133.Dv mn , 134.Dv noon . 135.Pp 136The months: 137.Dv january , 138.Dv february , 139.Dv march , 140.Dv april , 141.Dv may , 142.Dv june , 143.Dv july , 144.Dv august , 145.Dv september , 146.Dv october , 147.Dv november , 148.Dv december , 149and common abbreviations for them. 150.Pp 151The days of the week: 152.Dv sunday , 153.Dv monday , 154.Dv tuesday , 155.Dv wednesday , 156.Dv thursday , 157.Dv friday , 158.Dv saturday , 159and common abbreviations for them. 160.Pp 161Time units: 162.Dv year , 163.Dv month , 164.Dv fortnight , 165.Dv week , 166.Dv day , 167.Dv hour , 168.Dv minute , 169.Dv min , 170.Dv second , 171.Dv sec , 172.Dv tomorrow , 173.Dv yesterday . 174.Pp 175Timezone names: 176.Dv gmt (+0000) , 177.Dv ut (+0000) , 178.Dv utc (+0000) , 179.Dv wet (+0000) , 180.Dv bst (+0100) , 181.Dv wat (-0100) , 182.Dv at (-0200) , 183.Dv nft (-0330) , 184.Dv nst (-0330) , 185.Dv ndt (-0230) , 186.Dv ast (-0400) , 187.Dv adt (-0300) , 188.Dv est (-0500) , 189.Dv edt (-0400) , 190.Dv cst (-0600) , 191.Dv cdt (-0500) , 192.Dv mst (-0700) , 193.Dv mdt (-0600) , 194.Dv pst (-0800) , 195.Dv pdt (-0700) , 196.Dv yst (-0900) , 197.Dv ydt (-0800) , 198.Dv hst (-1000) , 199.Dv hdt (-0900) , 200.Dv cat (-1000) , 201.Dv ahst (-1000) , 202.Dv nt (-1100) , 203.Dv idlw (-1200) , 204.Dv cet (+0100) , 205.Dv met (+0100) , 206.Dv mewt (+0100) , 207.Dv mest (+0200) , 208.Dv swt (+0100) , 209.Dv sst (+0200) , 210.Dv fwt (+0100) , 211.Dv fst (+0200) , 212.Dv eet (+0200) , 213.Dv bt (+0300) , 214.Dv it (+0330) , 215.Dv zp4 (+0400) , 216.Dv zp5 (+0500) , 217.Dv ist (+0550) , 218.Dv zp6 (+0600) , 219.Dv ict (+0700) , 220.Dv wast (+0800) , 221.Dv wadt (+0900) , 222.Dv awst (+0800) , 223.Dv awdt (+0900) , 224.Dv cct (+0800) , 225.Dv sgt (+0800) , 226.Dv hkt (+0800) , 227.Dv jst (+0900) , 228.Dv cast (+0930) , 229.Dv cadt (+1030) , 230.Dv acst (+0930) , 231.Dv acst (+1030) , 232.Dv east (+1000) , 233.Dv eadt (+1100) , 234.Dv aest (+1000) , 235.Dv aedt (+1100) , 236.Dv gst (+1000) , 237.Dv nzt (+1200) , 238.Dv nzst (+1200) , 239.Dv nzdt (+1300) , 240.Dv idle (+1200) . 241.Pp 242The timezone names specify an offset from Coordinated Universal Time (UTC) 243and do not imply validating the time/date to be reasonable in any zone 244that happens to use the abbreviation specified. 245.Pp 246A variety of unambiguous dates are recognized: 247.Bl -tag -compact -width "20 Jun 1994" 248.It 9/10/69 249For years between 70-99 we assume 1900+ and for years between 0-69 250we assume 2000+. 251.It 2006-11-17 252An ISO-8601 date. 253.It 69-09-10 254The year in an ISO-8601 date is always taken literally, 255so this is the year 69, not 2069. 256.It 10/1/2000 257October 1, 2000; the common, but bizarre, US format. 258.It 20 Jun 1994 259.It 23jun2001 260.It 1-sep-06 261Other common abbreviations. 262.It 1/11 263The year can be omitted. 264This is the US month/day format. 265.El 266.Pp 267Standard e-mail (RFC822, RFC2822, etc) 268formats and the output from 269.Xr date 1 , 270and 271.Xr asctime 3 272are all supported as input. 273.Pp 274As well as times: 275.Bl -tag -compact -width 12:11:01.000012 276.It 10:01 277.It 10:12pm 278.It 12:11:01.000012 279.It 12:21-0500 280.El 281Fractions of seconds (after a decimal point) are parsed, but ignored. 282.Pp 283Relative items are also supported: 284.Bl -tag -compact -width "this thursday" 285.It -1 month 286.It last friday 287.It one week ago 288.It this thursday 289.It next sunday 290.It +2 years 291.El 292.Pp 293Note that, as a special case for 294.Dv midnight 295with the name of a day only, 296.Dq "midnight tuesday" 297implies 00:00 at the beginning of Tuesday, whereas 298.Dq "Sat mn" 299implies 00:00 at the end of Saturday (i.e. early Sunday morning.) 300.Pp 301Seconds since epoch, UTC, (also known as UNIX time) are also supported: 302.Bl -tag -compact -width "@735275209" 303.It @735275209 304Tue Apr 20 03:06:49 UTC 1993 305.El 306provided that the value given is within the range 307that can be represented as a 308.Va "struct tm" . 309Negative values 310(times before the epoch) 311are permitted, but no other significant data. 312.Pp 313Text in 314.Ar datestr 315enclosed in parentheses 316.Ql \&( 317and 318.Ql \&) 319is treated as a comment, and ignored. 320Parentheses nest (the comment ends when there have 321been the same number of closing parentheses as there 322were opening parentheses.) 323There is no escape character in comments, 324.Ql \&) 325always ends 326(or decreases the nesting level of) 327the comment. 328.Sh RETURN VALUES 329.Fn parsedate 330returns the number of seconds passed since, 331or before (if negative,) 332the Epoch, or 333.Dv \-1 334if the date could not be parsed properly. 335A non-error result of 336.Dv \-1 337can be distinguished from an error by setting 338.Va errno 339to 340.Dv 0 341before calling 342.Fn parsedate , 343and checking the value of 344.Va errno 345afterwards. 346.Sh ENVIRONMENT 347If the 348.Ar tzoff 349parameter is given as 350.Dv NULL , 351then: 352.Bl -tag -width iTZ 353.It Ev TZ 354The timezone to which the input is relative, 355when no zone information is otherwise specified in the 356.Ar datestr 357input. 358.El 359.Sh SEE ALSO 360.Xr date 1 , 361.Xr touch 1 , 362.Xr errno 2 , 363.Xr ctime 3 , 364.\" WTF ???? eeprom(8)!! Why? Just because it calls this function? Weird! 365.Xr eeprom 8 366.Sh HISTORY 367The parser used in 368.Fn parsedate 369was originally written by Steven M. Bellovin while at the University 370of North Carolina at Chapel Hill. 371It was later tweaked by a couple of people on Usenet. 372Completely overhauled by Rich $alz and Jim Berets in August, 1990. 373.Pp 374The 375.Fn parsedate 376function first appeared in 377.Nx 4.0 . 378.Sh BUGS 379.Bl -tag -compact -width 1 380.It 1 381The 382.Fn parsedate 383function is not re-entrant or thread-safe. 384.It 2 385The 386.Fn parsedate 387function assumes years less than 0 mean \(mi 388.Fa year , 389and in non ISO formats, 390that years less than 70 mean 2000 + 391.Fa year , 392otherwise 393years less than 100 mean 1900 + 394.Fa year . 395.It 3 396The 397.Fn parsedate 398function accepts 399.Dq "12 am" 400where 401.Dq "12 midnight" 402is correct, and similarly 403.Dq "12 pm" 404for 405.Dq "12 noon" . 406The correct forms are also accepted. 407.It 4 408There are various weird cases that are hard to explain, 409but are nevertheless considered correct. 410.It 5 411It is very hard to specify years BC, 412and in any case, 413conversions of times before the 414commencement of the modern Gregorian calendar 415(when that occurred depends upon location, 416but late 16th century is a rough guide) 417are suspicious at best, 418and depending upon context, 419often just plain wrong. 420.It 6 421Despite what is stated above, 422.Dq next 423is actually 2. 424The input 425.Dq "next January" , 426instead of producing a timestamp for January of the 427following year, produces one for January 2nd, of the 428current year. 429Use caution with 430.Dq next 431it rarely does what humans expect. 432.El 433