1.\" $NetBSD: parsedate.3,v 1.15 2014/10/08 22:10:04 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 October 8, 2014 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, or one = 781, 79.Dv second 80is unused so that it is not confused with 81.Dq seconds , 82.Dv two = 832, 84.Dv third or three = 853, 86.Dv fourth or four = 874, 88.Dv fifth or five = 895, 90.Dv sixth or six = 916, 92.Dv seventh or seven = 937, 94.Dv eighth or eight = 958, 96.Dv ninth or nine = 979, 98.Dv tenth or ten = 9910, 100.Dv eleventh or eleven = 10111, 102.Dv twelfth or twelve = 10312. 104.Pp 105The following words are recognized in English only: 106.Dv AM , 107.Dv PM , 108.Dv a.m. , 109.Dv p.m. 110.Pp 111The months: 112.Dv january , 113.Dv february , 114.Dv march , 115.Dv april , 116.Dv may , 117.Dv june , 118.Dv july , 119.Dv august , 120.Dv september , 121.Dv sept , 122.Dv october , 123.Dv november , 124.Dv december , 125.Pp 126The days of the week: 127.Dv sunday , 128.Dv monday , 129.Dv tuesday , 130.Dv tues , 131.Dv wednesday , 132.Dv wednes , 133.Dv thursday , 134.Dv thur , 135.Dv thurs , 136.Dv friday , 137.Dv saturday . 138.Pp 139Time units: 140.Dv year , 141.Dv month , 142.Dv fortnight , 143.Dv week , 144.Dv day , 145.Dv hour , 146.Dv minute , 147.Dv min , 148.Dv second , 149.Dv sec , 150.Dv tomorrow , 151.Dv yesterday . 152.Pp 153Timezone names: 154.Dv gmt , 155.Dv ut , 156.Dv utc , 157.Dv wet , 158.Dv bst , 159.Dv wat , 160.Dv at , 161.Dv ast , 162.Dv adt , 163.Dv est , 164.Dv edt , 165.Dv cst , 166.Dv cdt , 167.Dv mst , 168.Dv mdt , 169.Dv pst , 170.Dv pdt , 171.Dv yst , 172.Dv ydt , 173.Dv hst , 174.Dv hdt , 175.Dv cat , 176.Dv ahst , 177.Dv nt , 178.Dv idlw , 179.Dv cet , 180.Dv met , 181.Dv mewt , 182.Dv mest , 183.Dv swt , 184.Dv sst , 185.Dv fwt , 186.Dv fst , 187.Dv eet , 188.Dv bt , 189.Dv zp4 , 190.Dv zp5 , 191.Dv zp6 , 192.Dv wast , 193.Dv wadt , 194.Dv cct , 195.Dv jst , 196.Dv east , 197.Dv eadt , 198.Dv gst , 199.Dv nzt , 200.Dv nzst , 201.Dv nzdt , 202.Dv idle . 203.Pp 204A variety of unambiguous dates are recognized: 205.Bl -tag -compact -width "20 Jun 1994" 206.It 9/10/69 207For years between 69-99 we assume 1900+ and for years between 0-68 208we assume 2000+. 209.It 2006-11-17 210An ISO-8601 date. 211.It 69-09-10 212The year in an ISO-8601 date is always taken literally, 213so this is the year 69, not 2069. 214.It 10/1/2000 215October 10, 2000; the common US format. 216.It 20 Jun 1994 217.It 23jun2001 218.It 1-sep-06 219Other common abbreviations. 220.It 1/11 221The year can be omitted. 222This is the US month/day format. 223.El 224.Pp 225As well as times: 226.Bl -tag -compact -width 12:11:01.000012 227.It 10:01 228.It 10:12pm 229.It 12:11:01.000012 230.It 12:21-0500 231.El 232.Pp 233Relative items are also supported: 234.Bl -tag -compact -width "this thursday" 235.It -1 month 236.It last friday 237.It one week ago 238.It this thursday 239.It next sunday 240.It +2 years 241.El 242.Pp 243Seconds since epoch (also known as UNIX time) are also supported: 244.Bl -tag -compact -width "@735275209" 245.It @735275209 246Tue Apr 20 03:06:49 UTC 1993 247.El 248.Sh RETURN VALUES 249.Fn parsedate 250returns the number of seconds passed since the Epoch, or 251.Dv \-1 252if the date could not be parsed properly. 253A non-error result of 254.Dv \-1 255can be distinguished from an error by setting 256.Va errno 257to 258.Dv 0 259before calling 260.Fn parsedate , 261and checking the value of 262.Va errno 263afterwards. 264.Sh SEE ALSO 265.Xr date 1 , 266.Xr errno 2 , 267.Xr eeprom 8 268.Sh HISTORY 269The parser used in 270.Fn parsedate 271was originally written by Steven M. Bellovin while at the University 272of North Carolina at Chapel Hill. 273It was later tweaked by a couple of people on Usenet. 274Completely overhauled by Rich $alz and Jim Berets in August, 1990. 275.Pp 276The 277.Fn parsedate 278function first appeared in 279.Nx 4.0 . 280.Sh BUGS 281.Bl -tag -compact -width 1 282.It 1 283The 284.Fn parsedate 285function is not re-entrant or thread-safe. 286.It 2 287The 288.Fn parsedate 289function cannot compute days before the unix epoch (19700101). 290.It 3 291The 292.Fn parsedate 293function assumes years less than 0 mean - 294.Fa year , 295years less than 70 mean 2000 + 296.Fa year , 297years less than 100 mean 1900 + 298.Fa year . 299.El 300