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. 233