1.\" $NetBSD: parsedate.3,v 1.7 2010/08/28 13:42:07 tron 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 Aug 28, 2010 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 and an optional timezone offset in seconds specified in 50.Ar tzoff . 51If either 52.Ar time 53or 54.Ar tzoff 55are 56.Dv NULL , 57then the current time and timezone offset are used. 58.Pp 59The 60.Ar datestr 61is a sequence of white-space separated items. 62The white-space is optional the concatenated items are not ambiguous. 63An empty 64.Ar datestr 65is equivalent to midnight today (the beginning of this day). 66.Pp 67The following words have the indicated numeric meanings: 68.Dv last = 69\-1, 70.Dv this = 710, 72.Dv first or next 731, 74.Dv second 75is unused so that it is not confused with 76.Dq seconds , 77.Dv third = 783, 79.Dv fourth = 804, 81.Dv fifth = 825, 83.Dv sixth = 846, 85.Dv seventh = 867, 87.Dv eighth = 888, 89.Dv ninth = 909, 91.Dv tenth = 9210, 93.Dv eleventh = 9411, 95.Dv twelfth = 9612. 97.Pp 98The following words are recognized in English only: 99.Dv AM , 100.Dv PM , 101.Dv a.m. , 102.Dv p.m. 103.Pp 104The months: 105.Dv january , 106.Dv february , 107.Dv march , 108.Dv april , 109.Dv may , 110.Dv june , 111.Dv july , 112.Dv august , 113.Dv september , 114.Dv sept , 115.Dv october , 116.Dv november , 117.Dv december , 118.Pp 119The days of the week: 120.Dv sunday , 121.Dv monday , 122.Dv tuesday , 123.Dv tues , 124.Dv wednesday , 125.Dv wednes , 126.Dv thursday , 127.Dv thur , 128.Dv thurs , 129.Dv friday , 130.Dv saturday . 131.Pp 132Time units: 133.Dv year , 134.Dv month , 135.Dv fortnight , 136.Dv week , 137.Dv day , 138.Dv hour , 139.Dv minute , 140.Dv min , 141.Dv second , 142.Dv sec , 143.Dv tomorrow , 144.Dv yesterday . 145.Pp 146Timezone names: 147.Dv gmt , 148.Dv ut , 149.Dv utc , 150.Dv wet , 151.Dv bst , 152.Dv wat , 153.Dv at , 154.Dv ast , 155.Dv adt , 156.Dv est , 157.Dv edt , 158.Dv cst , 159.Dv cdt , 160.Dv mst , 161.Dv mdt , 162.Dv pst , 163.Dv pdt , 164.Dv yst , 165.Dv ydt , 166.Dv hst , 167.Dv hdt , 168.Dv cat , 169.Dv ahst , 170.Dv nt , 171.Dv idlw , 172.Dv cet , 173.Dv met , 174.Dv mewt , 175.Dv mest , 176.Dv swt , 177.Dv sst , 178.Dv fwt , 179.Dv fst , 180.Dv eet , 181.Dv bt , 182.Dv zp4 , 183.Dv zp5 , 184.Dv zp6 , 185.Dv wast , 186.Dv wadt , 187.Dv cct , 188.Dv jst , 189.Dv east , 190.Dv eadt , 191.Dv gst , 192.Dv nzt , 193.Dv nzst , 194.Dv nzdt , 195.Dv idle . 196.Pp 197A variety of unambiguous dates are recognized: 198.Bl -tag -compact -width "20 Jun 1994" 199.It 69-09-10 200For years between 69-99 we assume 1900+ and for years between 0-68 201we assume 2000+. 202.It 2006-11-17 203An ISO-8601 date. 204.It 10/1/2000 205October 10, 2000; the common US format. 206.It 20 Jun 1994 207.It 23jun2001 208.It 1-sep-06 209Other common abbreviations. 210.It 1/11 211the year can be omitted 212.El 213.Pp 214As well as times: 215.Bl -tag -compact -width 12:11:01.000012 216.It 10:01 217.It 10:12pm 218.It 12:11:01.000012 219.It 12:21-0500 220.El 221.Pp 222Relative items are also supported: 223.Bl -tag -compact -width "this thursday" 224.It -1 month 225.It last friday 226.It one week ago 227.It this thursday 228.It next sunday 229.It +2 years 230.El 231.Pp 232Seconds since epoch (also known as UNIX time) are also supported: 233.Bl -tag -compact -width "@735275209" 234.It @735275209 235Tue Apr 20 03:06:49 UTC 1993 236.El 237.Sh RETURN VALUES 238.Fn parsedate 239returns the number of seconds passed since the Epoch, or 240.Dv \-1 241if the date could not be parsed properly. 242.Sh SEE ALSO 243.Xr date 1 , 244.Xr eeprom 8 245.Sh BUGS 246The parsedate function is not re-entrant or thread-safe. 247.Sh HISTORY 248The parser used in 249.Fn parsedate 250was originally written by Steven M. Bellovin while at the University 251of North Carolina at Chapel Hill. 252It was later tweaked by a couple of people on Usenet. 253Completely overhauled by Rich $alz and Jim Berets in August, 1990. 254.Pp 255The 256.Fn parsedate 257function first appeared in 258.Nx 4.0 . 259