libc: Bring in getdate() from NetBSD for POSIX conformance.
[dragonfly.git] / lib / libc / stdtime / getdate.3
CommitLineData
28bfdfe6
SW
1.\" $NetBSD: getdate.3,v 1.10 2018/02/11 13:28:49 wiz Exp $
2.\"
3.\" Copyright (c) 2009, 2011, 2012, The NetBSD Foundation.
4.\" All Rights Reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Brian Ginsbach.
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 May 24, 2020
31.Dt GETDATE 3
32.Os
33.Sh NAME
34.Nm getdate ,
35.Nm getdate_err
36.Nd convert user format date and time
37.Sh LIBRARY
38.Lb libc
39.Sh SYNOPSIS
40.In time.h
41.Ft "struct tm *"
42.Fo "getdate"
43.Fa "const char *str"
44.Fc
45.Vt extern int getdate_err ;
46.Sh DESCRIPTION
47The
48.Fn getdate
49function converts a date or time character string pointed to by
50.Fa str
51into a static
52.Vt tm
53structure described in
54.Xr tm 3 .
55.Pp
56The input string is parsed and interpreted using templates.
57A text file containing templates is specified by the
58environment variable
59.Ev DATEMSK .
60This should contain the full path to the template file.
61Lines in the template file represent acceptable date and/or time
62conversion specifications.
63These specifications are similar to those given for
64.Xr strptime 3 .
65The first line in the template file that matches the input string
66is used to interpret and convert to internal time format.
67.Ss Internal Format Conversion
68The following rules apply to converting the input into the internal format.
69.Bl -bullet -offset indent
70.It
71If only the weekday is given, the conversion assumes today when the
72weekday matches today or the first future matching weekday.
73.It
74If only the month and no year is given, the conversion assumes the
75current month when the month matches or the first future matching month.
76The first day of the month is assumed if no day is given.
77.It
78If only the year is given, the values of the
79.Fa tm_mon ,
80.Fa tm_mday ,
81.Fa tm_wday ,
82.Fa tm_yday ,
83and
84.Fa tm_isdst
85members of the returned
86.Vt "struct tm"
87are unspecified.
88.It
89If the century is given, but the year within the century is not given,
90the conversion assumes the current year.
91.It
92If no hour, minute, and second are given, the conversion assumes
93the current hour, minute, and second.
94.It
95If no date is given, the conversion assumes today when the given hour
96is greater than the current hour and tomorrow when the given hour is less.
97.It
98If
99.Cm \&%Z
100is being scanned, then the broken-down time is based on the
101current time of the matched timezone and not the current runtime
102environment timezone.
103.El
104.Sh RETURN VALUES
105If successful, the
106.Fn getdate
107function returns a pointer to a static
108.Vt tm
109structure containing the broken-down time.
110Otherwise, a null pointer is returned and
111.Va getdate_err
112is set to indicate the error.
113.Pp
114The variable
115.Va getdate_err
116can have the following values:
117.Bl -tag -width NNN
118.It 1
119.Ev DATEMSK
120environment variable is null or undefined.
121.It 2
122Cannot open the template file for reading.
123.It 3
124Get file status failed for template file.
125.It 4
126Template file is not a regular file.
127.It 5
128Encountered an error while reading the template file.
129.It 6
130Cannot allocate memory.
131.It 7
132Input string does not match any line in the template file.
133.It 8
134Input string is invalid (for example, February 31)
135or could not be represented in a
136.Vt time_t .
137.El
138.Sh ENVIRONMENT
139.Bl -tag -width DATEMSK
140.It Ev DATEMSK
141The full path to the text file containing the templates
142for acceptable date and/or time conversions.
143.El
144.Sh FILES
145.Bl -tag -width DATEMSK
146.It Pa /usr/share/examples/getdate/datemsk.template
147An example template file that could be specified via the
148.Ev DATEMSK
149environment variable.
150.El
151.Sh EXAMPLES
152The following example shows the possible contents of a template file:
153.Pp
154.Bd -literal -offset indent -compact
155%m
156%A %B %d, %Y, %H:%M:%S
157%A
158%B
159%m/%d/%y %I %p
160%d,%m,%Y %H:%M
161at %A the %dst of %B in %Y
162run job at %I %p, %B %dnd
163%A den %d. %B %Y %H.%M Uhr
164.Ed
165.Pp
166The following are examples of valid input for the above template:
167.Pp
168.Bd -literal -offset indent -compact
16910/1/87 4 PM
170Friday
171Friday September 18, 1987, 10:30:30
17224,9,1986 10:30
173at monday the 1st of december in 1986
174run job at 3 PM, december 2nd
175.Ed
176.Pp
177The following examples show how local data and time specification can be
178defined in the template.
179.Bl -column -offset indent ".Li Friday 12:00:00" ".Sy Line in Template"
180.It Sy "Input String" Ta Sy "Line in Template"
181.It Li 11/27/86 Ta Li \&%m/\&%d/\&%y
182.It Li 27.11.86 Ta Li \&%d.\&%m.\&%y
183.It Li 86-11-27 Ta Li \&%y-\&%m-\&%d
184.It Li "Friday 12:00:00" Ta Li "\&%A \&%H:\&%M:\&%S"
185.El
186.Pp
187The following examples illustrate the Internal Format Conversion rules
188given that the current date is
189.Li "Mon Sep 22 12:19:47 EDT 1986"
190and the
191.Ev LC_TIME
192environment variable is set to the default C locale.
193.Bl -column -offset indent ".Li Jan Wed 1989" ".Sy Line in Template" ".Sy Date"
194.It Sy Input String Ta Sy Line in Template Ta Sy Date
195.It Li Mon Ta Li \&%a Ta Li "Mon Sep 22 12:19:47 EDT 1986"
196.It Li Sun Ta Li \&%a Ta Li "Sun Sep 28 12:19:47 EDT 1986"
197.It Li Fri Ta Li \&%a Ta Li "Fri Sep 26 12:19:47 EDT 1986"
198.It Li September Ta Li \&%B Ta Li "Mon Sep 1 12:19:47 EDT 1986"
199.It Li January Ta Li \&%B Ta Li "Thu Jan 1 12:19:47 EST 1987"
200.It Li December Ta Li \&%B Ta Li "Mon Dec 1 12:19:47 EST 1986"
201.It Li "Sep Mon" Ta Li "\&%b %a" Ta Li "Mon Sep 1 12:19:47 EDT 1986"
202.It Li "Jan Fri" Ta Li "\&%b %a" Ta Li "Fri Jan 2 12:19:47 EST 1987"
203.It Li "Dec Mon" Ta Li "\&%b %a" Ta Li "Mon Dec 1 12:19:47 EST 1986"
204.It Li "Jan Wed 1989" Ta Li "\&%b \&%a \&%Y" Ta Li "Wed Jan 4 12:19:47 EST 1989"
205.It Li "Fri 9" Ta Li "\&%a \&%H" Ta Li "Fri Sep 26 09:00:00 EDT 1986"
206.It Li "Feb 10:30" Ta Li "\&%b \&%H:\&%S" Ta Li "Sun Feb 1 10:00:30 EST 1987"
207.It Li 10:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 23 10:30:00 EDT 1986"
208.It Li 13:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 22 13:30:00 EDT 1986"
209.El
210.Sh SEE ALSO
211.Xr ctime 3 ,
212.Xr localtime 3 ,
213.Xr mktime 3 ,
214.Xr strftime 3 ,
215.Xr strptime 3 ,
216.Xr time 3
217.Sh STANDARDS
218The
219.Fn getdate
220function conforms to
221.St -p1003.1-2001 .
222.Sh HISTORY
223The
224.Nm
225function appeared in
226.At V.4 .
227.Sh BUGS
228The
229.Nm
230interface is inherently unsafe for multi-threaded programs or libraries,
231since it returns a pointer to a static variable and uses a global state
232variable.