1.\" $NetBSD: parsedate.3,v 1.20 2015/12/10 21:32:35 wiz 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 December 7, 2015 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 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.Dv dawn , 136.Dv sunup , 137.Dv sunset , 138.Dv sundown . 139.Pp 140The months: 141.Dv january , 142.Dv february , 143.Dv march , 144.Dv april , 145.Dv may , 146.Dv june , 147.Dv july , 148.Dv august , 149.Dv september , 150.Dv october , 151.Dv november , 152.Dv december , 153and common abbreviations for them. 154.Pp 155The days of the week: 156.Dv sunday , 157.Dv monday , 158.Dv tuesday , 159.Dv wednesday , 160.Dv thursday , 161.Dv friday , 162.Dv saturday . 163and common abbreviations for them. 164.Pp 165Time units: 166.Dv year , 167.Dv month , 168.Dv fortnight , 169.Dv week , 170.Dv day , 171.Dv hour , 172.Dv minute , 173.Dv min , 174.Dv second , 175.Dv sec , 176.Dv tomorrow , 177.Dv yesterday . 178.Pp 179Timezone names: 180.Dv gmt (+0000) , 181.Dv ut (+0000) , 182.Dv utc (+0000) , 183.Dv wet (+0000) , 184.Dv bst (+0100) , 185.Dv wat (-0100) , 186.Dv at (-0200) , 187.Dv nft (-0330) , 188.Dv nst (-0330) , 189.Dv ndt (-0230) , 190.Dv ast (-0400) , 191.Dv adt (-0300) , 192.Dv est (-0500) , 193.Dv edt (-0400) , 194.Dv cst (-0600) , 195.Dv cdt (-0500) , 196.Dv mst (-0700) , 197.Dv mdt (-0600) , 198.Dv pst (-0800) , 199.Dv pdt (-0700) , 200.Dv yst (-0900) , 201.Dv ydt (-0800) , 202.Dv hst (-1000) , 203.Dv hdt (-0900) , 204.Dv cat (-1000) , 205.Dv ahst (-1000) , 206.Dv nt (-1100) , 207.Dv idlw (-1200) , 208.Dv cet (+0100) , 209.Dv met (+0100) , 210.Dv mewt (+0100) , 211.Dv mest (+0200) , 212.Dv swt (+0100) , 213.Dv sst (+0200) , 214.Dv fwt (+0100) , 215.Dv fst (+0200) , 216.Dv eet (+0200) , 217.Dv bt (+0300) , 218.Dv it (+0330) , 219.Dv zp4 (+0400) , 220.Dv zp5 (+0500) , 221.Dv ist (+0550) , 222.Dv zp6 (+0600) , 223.Dv ict (+0700) , 224.Dv wast (+0800) , 225.Dv wadt (+0900) , 226.Dv awst (+0800) , 227.Dv awdt (+0900) , 228.Dv cct (+0800) , 229.Dv sgt (+0800) , 230.Dv hkt (+0800) , 231.Dv jst (+0900) , 232.Dv cast (+0930) , 233.Dv cadt (+1030) , 234.Dv acst (+0930) , 235.Dv acst (+1030) , 236.Dv east (+1000) , 237.Dv eadt (+1100) , 238.Dv aest (+1000) , 239.Dv aedt (+1100) , 240.Dv gst (+1000) , 241.Dv nzt (+1200) , 242.Dv nzst (+1200) , 243.Dv nzdt (+1300) , 244.Dv idle (+1200) . 245.Pp 246The timezone names specify an offset from Coordinated Universal Time (UTC) 247and do not imply validating the time/date to be reasonable in any zone 248that happens to use the abbreviation specified. 249.Pp 250A variety of unambiguous dates are recognized: 251.Bl -tag -compact -width "20 Jun 1994" 252.It 9/10/69 253For years between 70-99 we assume 1900+ and for years between 0-69 254we assume 2000+. 255.It 2006-11-17 256An ISO-8601 date. 257.It 69-09-10 258The year in an ISO-8601 date is always taken literally, 259so this is the year 69, not 2069. 260.It 10/1/2000 261October 1, 2000; the common, but bizarre, US format. 262.It 20 Jun 1994 263.It 23jun2001 264.It 1-sep-06 265Other common abbreviations. 266.It 1/11 267The year can be omitted. 268This is the US month/day format. 269.El 270.Pp 271Standard e-mail (RFC822, RFC2822, etc) 272formats and the output from 273.Xr date 1 , 274and 275.Xr asctime 3 276are all supported as input. 277.Pp 278As well as times: 279.Bl -tag -compact -width 12:11:01.000012 280.It 10:01 281.It 10:12pm 282.It 12:11:01.000012 283.It 12:21-0500 284.El 285Fractions of seconds (after a decimal point) are parsed, but ignored. 286.Pp 287Relative items are also supported: 288.Bl -tag -compact -width "this thursday" 289.It -1 month 290.It last friday 291.It one week ago 292.It this thursday 293.It next sunday 294.It +2 years 295.El 296.Pp 297Note that, as a special case for 298.Dv midnight 299with the name of a day only, 300.Dq "midnight tuesday" 301implies 00:00 at the beginning of Tuesday, whereas 302.Dq "Sat mn" 303implies 00:00 at the end of Saturday (i.e. early Sunday morning.) 304.Pp 305Seconds since epoch, UTC, (also known as UNIX time) are also supported: 306.Bl -tag -compact -width "@735275209" 307.It @735275209 308Tue Apr 20 03:06:49 UTC 1993 309.El 310provided that the value given is within the range 311that can be represented as a 312.Va "struct tm" . 313Negative values 314(times before the epoch) 315are permitted, but no other significant data. 316.Pp 317Text in 318.Ar datestr 319enclosed in parentheses 320.Ql \&( 321and 322.Ql \&) 323is treated as a comment, and ignored. 324Parentheses nest (the comment ends when there have 325been the same number of closing parentheses as there 326were opening parentheses.) 327There is no escape character in comments, 328.Ql \&) 329always ends 330(or decreases the nesting level of) 331the comment. 332.Sh RETURN VALUES 333.Fn parsedate 334returns the number of seconds passed since, 335or before (if negative,) 336the Epoch, or 337.Dv \-1 338if the date could not be parsed properly. 339A non-error result of 340.Dv \-1 341can be distinguished from an error by setting 342.Va errno 343to 344.Dv 0 345before calling 346.Fn parsedate , 347and checking the value of 348.Va errno 349afterwards. 350.Sh ENVIRONMENT 351If the 352.Ar tzoff 353parameter is given as 354.Dv NULL , 355then: 356.Bl -tag -width iTZ 357.It Ev TZ 358The timezone to which the input is relative, 359when no zone information is otherwise specified in the 360.Ar datestr 361input. 362.El 363.Sh SEE ALSO 364.Xr date 1 , 365.Xr touch 1 , 366.Xr errno 2 , 367.Xr ctime 3 , 368.\" WTF ???? eeprom(8)!! Why? Just because it calls this function? Weird! 369.Xr eeprom 8 370.Sh HISTORY 371The parser used in 372.Fn parsedate 373was originally written by Steven M. Bellovin while at the University 374of North Carolina at Chapel Hill. 375It was later tweaked by a couple of people on Usenet. 376Completely overhauled by Rich $alz and Jim Berets in August, 1990. 377.Pp 378The 379.Fn parsedate 380function first appeared in 381.Nx 4.0 . 382.Sh BUGS 383.Bl -tag -compact -width 1 384.It 1 385The 386.Fn parsedate 387function is not re-entrant or thread-safe. 388.It 2 389The 390.Fn parsedate 391function assumes years less than 0 mean \(mi 392.Fa year , 393and in non ISO formats, 394that years less than 70 mean 2000 + 395.Fa year , 396otherwise 397years less than 100 mean 1900 + 398.Fa year . 399.It 3 400There are various weird cases that are hard to explain, 401but are nevertheless considered correct. 402.It 4 403It is very hard to specify years BC, 404and in any case, 405conversions of times before the 406commencement of the modern Gregorian calendar 407(when that occurred depends upon location, 408but late 16th century is a rough guide) 409are suspicious at best, 410and depending upon context, 411often just plain wrong. 412.El 413