| blob | 46c560f45b3164a34aff1c30912680b2e329d0cd |
1 .\" $NetBSD: parsedate.3,v 1.4 2008/04/30 13:10:52 martin 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 November 17, 2006
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
43 The
44 .Nm parsedate
45 function parses a datetime from
46 .Ar datestr
47 described in english relative to an optional
48 .Ar time
49 point and an optional timezone offset in seconds specified in
50 .Ar tzoff .
51 If either
52 .Ar time
53 or
54 .Ar tzoff
55 are
56 .Dv NULL ,
57 then the current time and timezone offset are used.
58 .Pp
59 The
60 .Ar datestr
61 is a sequence of white-space separated items.
62 The white-space is optional the concatenated items are not ambiguous.
63 An empty
64 .Ar datestr
65 is equivalent to midnight today (the beginning of this day).
66 .Pp
67 The following words have the indicated numeric meanings:
68 .Dv last =
69 \-1,
70 .Dv this =
71 0,
72 .Dv first or next
73 1,
74 .Dv second
75 is unused so that it is not confused with
76 .Dq seconds ,
77 .Dv third =
78 3,
79 .Dv fourth =
80 4,
81 .Dv fifth =
82 5,
83 .Dv sixth =
84 6,
85 .Dv seventh =
86 7,
87 .Dv eighth =
88 8,
89 .Dv ninth =
90 9,
91 .Dv tenth =
92 10,
93 .Dv eleventh =
94 11,
95 .Dv twelfth =
96 12.
97 .Pp
98 The following words are recognized in English only:
99 .Dv AM ,
100 .Dv PM ,
101 .Dv a.m. ,
102 .Dv p.m.
103 .Pp
104 The 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
119 The 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
132 Time 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
146 Timezone 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
197 A variety of unambiguous dates are recognized:
198 .Bl -tag -compact -width "20 Jun 1994"
199 .It 69-09-10
200 For years between 69-99 we assume 1900+ and for years between 0-68
201 we assume 2000+.
202 .It 2006-11-17
203 An ISO-8601 date.
204 .It 10/1/2000
205 October 10, 2000; the common US format.
206 .It 20 Jun 1994
207 .It 23jun2001
208 .It 1-sep-06
209 Other common abbreviations.
210 .It 1/11
211 the year can be omitted
212 .El
213 .Pp
214 As 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
222 Relative 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 .Sh RETURN VALUES
232 .Fn parsedate
233 returns the number of seconds passed since the Epoch, or
234 .Dv \-1
235 if the date could not be parsed properly.
236 .Sh SEE ALSO
237 .Xr date 1 ,
238 .Xr eeprom 8
239 .Sh HISTORY
240 The parser used in
241 .Fn parsedate
242 was originally written by Steven M. Bellovin while at the University
243 of North Carolina at Chapel Hill.
244 It was later tweaked by a couple of people on Usenet.
245 Completely overhauled by Rich $alz and Jim Berets in August, 1990.
246 .Pp
247 The
248 .Fn parsedate
249 function first appeared in
250 .Nx 4.0 .