|File: [cvs.NetBSD.org] / src / lib / libutil / parsedate.3 (download)
Revision 1.24, Wed Mar 22 18:17:42 2017 UTC (3 years ago) by kre
CVS Tags: prg-localcount2-base3, prg-localcount2-base2, prg-localcount2-base1, prg-localcount2-base, prg-localcount2, phil-wifi-base, phil-wifi-20191119, phil-wifi-20190609, phil-wifi, pgoyette-localcount-20170426, pgoyette-compat-merge-20190127, pgoyette-compat-base, pgoyette-compat-20190127, pgoyette-compat-20190118, pgoyette-compat-1226, pgoyette-compat-1126, pgoyette-compat-1020, pgoyette-compat-0930, pgoyette-compat-0906, pgoyette-compat-0728, pgoyette-compat-0625, pgoyette-compat-0521, pgoyette-compat-0502, pgoyette-compat-0422, pgoyette-compat-0415, pgoyette-compat-0407, pgoyette-compat-0330, pgoyette-compat-0322, pgoyette-compat-0315, pgoyette-compat, perseant-stdc-iso10646-base, perseant-stdc-iso10646, netbsd-9-base, netbsd-9-0-RELEASE, netbsd-9-0-RC2, netbsd-9-0-RC1, netbsd-9, netbsd-8-base, netbsd-8-1-RELEASE, netbsd-8-1-RC1, netbsd-8-0-RELEASE, netbsd-8-0-RC2, netbsd-8-0-RC1, netbsd-8, matt-nb8-mediatek-base, matt-nb8-mediatek, bouyer-socketcan-base1, HEAD
Changes since 1.23: +13 -1
parsedate.y: meaningless KNF of a comment (no code changes)
parsedate.3: add an item in BUGS noting the weirdness of "next"
The real purpose of this commit is to supply the following message
which should be used for the immediately previous commit, replacing
its commit message (the two are similar, but definitely not the
same). With thanks to gdt@ for pointing out one of the (many) errors
in the previous message (and noting others I had already seen).
Make parsedate handle "12 noon" and "12 midnight" (including when the
time given is "12:00" or "12:00:00") - but only for exactly 12 o'clock.
"12:00:01" is am or pm, not noon or midnight.
"12 am" remains as an alias for "12 midnight", and "12 pm" for noon,
though both are strictly (pedanticly) invalid (and meaningless.)
Note that "12 midnight" (or "12 am") means 00:00:00 (ie: midnight at
the start of the day, not at the end.)
.\" $NetBSD: parsedate.3,v 1.24 2017/03/22 18:17:42 kre Exp $
.\" Copyright (c) 2006 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Christos Zoulas.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.Dd March 22, 2017
.Dt PARSEDATE 3
.Nd date parsing function
.Fn parsedate "const char *datestr" "const time_t *time" "const int *tzoff"
function parses a datetime from
described in English relative to an optional
and an optional timezone offset (in minutes behind/west of UTC)
.Ar tzoff .
then the current time is used.
.Dv NULL ,
then the current time zone is used.
is a sequence of white-space separated items.
The white-space is optional if the concatenated items are not ambiguous.
is equivalent to midnight today (the beginning of this day).
The following words have the indicated numeric meanings:
.Dv last =
.Dv this =
.Dv first , next ,
.Dv one =
is unused so that it is not confused with
.Dq seconds ,
.Dv two =
.Dv three =
.Dv four =
.Dv five =
.Dv six =
.Dv seven =
.Dv eight =
.Dv nine =
.Dv ten =
.Dv eleven =
.Dv twelve =
The following words are recognized in English only:
.Dv AM ,
.Dv PM ,
.Dv a.m. ,
.Dv p.m. ,
.Dv midnight ,
.Dv mn ,
.Dv noon .
.Dv january ,
.Dv february ,
.Dv march ,
.Dv april ,
.Dv may ,
.Dv june ,
.Dv july ,
.Dv august ,
.Dv september ,
.Dv october ,
.Dv november ,
.Dv december ,
and common abbreviations for them.
The days of the week:
.Dv sunday ,
.Dv monday ,
.Dv tuesday ,
.Dv wednesday ,
.Dv thursday ,
.Dv friday ,
.Dv saturday ,
and common abbreviations for them.
.Dv year ,
.Dv month ,
.Dv fortnight ,
.Dv week ,
.Dv day ,
.Dv hour ,
.Dv minute ,
.Dv min ,
.Dv second ,
.Dv sec ,
.Dv tomorrow ,
.Dv yesterday .
.Dv gmt (+0000) ,
.Dv ut (+0000) ,
.Dv utc (+0000) ,
.Dv wet (+0000) ,
.Dv bst (+0100) ,
.Dv wat (-0100) ,
.Dv at (-0200) ,
.Dv nft (-0330) ,
.Dv nst (-0330) ,
.Dv ndt (-0230) ,
.Dv ast (-0400) ,
.Dv adt (-0300) ,
.Dv est (-0500) ,
.Dv edt (-0400) ,
.Dv cst (-0600) ,
.Dv cdt (-0500) ,
.Dv mst (-0700) ,
.Dv mdt (-0600) ,
.Dv pst (-0800) ,
.Dv pdt (-0700) ,
.Dv yst (-0900) ,
.Dv ydt (-0800) ,
.Dv hst (-1000) ,
.Dv hdt (-0900) ,
.Dv cat (-1000) ,
.Dv ahst (-1000) ,
.Dv nt (-1100) ,
.Dv idlw (-1200) ,
.Dv cet (+0100) ,
.Dv met (+0100) ,
.Dv mewt (+0100) ,
.Dv mest (+0200) ,
.Dv swt (+0100) ,
.Dv sst (+0200) ,
.Dv fwt (+0100) ,
.Dv fst (+0200) ,
.Dv eet (+0200) ,
.Dv bt (+0300) ,
.Dv it (+0330) ,
.Dv zp4 (+0400) ,
.Dv zp5 (+0500) ,
.Dv ist (+0550) ,
.Dv zp6 (+0600) ,
.Dv ict (+0700) ,
.Dv wast (+0800) ,
.Dv wadt (+0900) ,
.Dv awst (+0800) ,
.Dv awdt (+0900) ,
.Dv cct (+0800) ,
.Dv sgt (+0800) ,
.Dv hkt (+0800) ,
.Dv jst (+0900) ,
.Dv cast (+0930) ,
.Dv cadt (+1030) ,
.Dv acst (+0930) ,
.Dv acst (+1030) ,
.Dv east (+1000) ,
.Dv eadt (+1100) ,
.Dv aest (+1000) ,
.Dv aedt (+1100) ,
.Dv gst (+1000) ,
.Dv nzt (+1200) ,
.Dv nzst (+1200) ,
.Dv nzdt (+1300) ,
.Dv idle (+1200) .
The timezone names specify an offset from Coordinated Universal Time (UTC)
and do not imply validating the time/date to be reasonable in any zone
that happens to use the abbreviation specified.
A variety of unambiguous dates are recognized:
.Bl -tag -compact -width "20 Jun 1994"
For years between 70-99 we assume 1900+ and for years between 0-69
we assume 2000+.
An ISO-8601 date.
The year in an ISO-8601 date is always taken literally,
so this is the year 69, not 2069.
October 1, 2000; the common, but bizarre, US format.
.It 20 Jun 1994
Other common abbreviations.
The year can be omitted.
This is the US month/day format.
Standard e-mail (RFC822, RFC2822, etc)
formats and the output from
.Xr date 1 ,
.Xr asctime 3
are all supported as input.
As well as times:
.Bl -tag -compact -width 12:11:01.000012
Fractions of seconds (after a decimal point) are parsed, but ignored.
Relative items are also supported:
.Bl -tag -compact -width "this thursday"
.It -1 month
.It last friday
.It one week ago
.It this thursday
.It next sunday
.It +2 years
Note that, as a special case for
with the name of a day only,
.Dq "midnight tuesday"
implies 00:00 at the beginning of Tuesday, whereas
.Dq "Sat mn"
implies 00:00 at the end of Saturday (i.e. early Sunday morning.)
Seconds since epoch, UTC, (also known as UNIX time) are also supported:
.Bl -tag -compact -width "@735275209"
Tue Apr 20 03:06:49 UTC 1993
provided that the value given is within the range
that can be represented as a
.Va "struct tm" .
(times before the epoch)
are permitted, but no other significant data.
enclosed in parentheses
is treated as a comment, and ignored.
Parentheses nest (the comment ends when there have
been the same number of closing parentheses as there
were opening parentheses.)
There is no escape character in comments,
(or decreases the nesting level of)
.Sh RETURN VALUES
returns the number of seconds passed since,
or before (if negative,)
the Epoch, or
if the date could not be parsed properly.
A non-error result of
can be distinguished from an error by setting
.Fn parsedate ,
and checking the value of
parameter is given as
.Dv NULL ,
.Bl -tag -width iTZ
.It Ev TZ
The timezone to which the input is relative,
when no zone information is otherwise specified in the
.Sh SEE ALSO
.Xr date 1 ,
.Xr touch 1 ,
.Xr errno 2 ,
.Xr ctime 3 ,
.\" WTF ???? eeprom(8)!! Why? Just because it calls this function? Weird!
.Xr eeprom 8
The parser used in
was originally written by Steven M. Bellovin while at the University
of North Carolina at Chapel Hill.
It was later tweaked by a couple of people on Usenet.
Completely overhauled by Rich $alz and Jim Berets in August, 1990.
function first appeared in
.Nx 4.0 .
.Bl -tag -compact -width 1
function is not re-entrant or thread-safe.
function assumes years less than 0 mean \(mi
.Fa year ,
and in non ISO formats,
that years less than 70 mean 2000 +
.Fa year ,
years less than 100 mean 1900 +
.Fa year .
.Dq "12 am"
.Dq "12 midnight"
is correct, and similarly
.Dq "12 pm"
.Dq "12 noon" .
The correct forms are also accepted.
There are various weird cases that are hard to explain,
but are nevertheless considered correct.
It is very hard to specify years BC,
and in any case,
conversions of times before the
commencement of the modern Gregorian calendar
(when that occurred depends upon location,
but late 16th century is a rough guide)
are suspicious at best,
and depending upon context,
often just plain wrong.
Despite what is stated above,
is actually 2.
.Dq "next January" ,
instead of producing a timestamp for January of the
following year, produces one for January 2nd, of the
Use caution with
it rarely does what humans expect.