1.\" $NetBSD: getdate.3,v 1.2 2011/04/14 05:50:49 jruoho Exp $ 2.\" 3.\" Copyright (c) 2009, 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 April 14, 2011 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.Va 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.Va "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 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.Va 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 135.Pq for example February 31 136or could not be represented in a 137.Va time_t . 138.El 139.Sh ENVIRONMENT 140.Bl -tag -width DATEMSK 141.It Ev DATEMSK 142The full path to the text file containing the templates 143for acceptable date and/or time conversions. 144.El 145.Sh FILES 146.Bl -tag -width DATEMSK 147.It Pa /usr/share/examples/getdate/datemsk.template 148An example template file that could be specified via the 149.Ev DATEMSK 150environment variable. 151.El 152.Sh EXAMPLES 153The following example shows the possible contents of a template file: 154.Pp 155.Bd -literal -offset indent -compact 156%m 157%A %B %d, %Y, %H:%M:%S 158%A 159%B 160%m/%d/%y %I %p 161%d,%m,%Y %H:%M 162at %A the %dst of %B in %Y 163run job at %I %p, %B %dnd 164%A den %d. %B %Y %H.%M Uhr 165.Ed 166.Pp 167The following are examples of valid input for the above template: 168.Pp 169.Bd -literal -offset indent -compact 17010/1/87 4 PM 171Friday 172Firday September 18, 1987, 10:30:30 17324,9,1986 10:30 174at monday the 1st of december in 1986 175run job at 3 PM, december 2nd 176.Ed 177.Pp 178The following examples show how local data and time specification can be 179defined in the template. 180.Pp 181.Bl -column -offset indent ".Sy Input String" ".Sy Line in Template" 182.It Sy "Input String" Ta Sy "Line in Template" 183.It Li 11/27/86 Ta Li \&%m/\&%d/\&%y 184.It Li 27.11.86 Ta Li \&%d.\&%m/\&%y 185.It Li 86-11-27 Ta Li \&%y-\&%m-\&%d 186.It Li "Friday 12:00:00" Ta "\&%A \&%H:\&%M:\&%S" 187.El 188.Pp 189The following examples illustrate the Internal Format Conversion rules 190given that the current date is 191.Li "Mon Sep 22 12:19:47 EDT 1986" 192and the 193.Ev LC_TIME 194environment variable is set to the default C locale. 195.Pp 196.Bl -column -offset indent ".Sy Input String" ".Sy Line in Template" ".Sy Date" 197.It Sy Input String Ta Sy Line in Template Ta Sy Date 198.It Li Mon Ta Li \&%a Ta Li "Mon Sep 22 12:19:47 EDT 1986" 199.It Li Sun Ta Li \&%a Ta Li "Sun Sep 28 12:19:47 EDT 1986" 200.It Li Fri Ta Li \&%a Ta Li "Sun Sep 26 12:19:47 EDT 1986" 201.It Li September Ta Li \&%B Ta Li "Mon Sep 1 12:19:47 EDT 1986" 202.It Li January Ta Li \&%B Ta Li "Thu Jan 1 12:19:47 EST 1987" 203.It Li December Ta Li \&%B Ta Li "Mon Dec 1 12:19:47 EST 1987" 204.It Li "Sep Mon" Ta Li "\&%b %a" Ta Li "Mon Sep 1 12:19:47 EDT 1986" 205.It Li "Jan Fri" Ta Li "\&%b %a" Ta Li "Fri Jan 2 12:19:47 EDT 1987" 206.It Li "Dec Mon" Ta Li "\&%b %a" Ta Li "Mon Dec 1 12:19:47 EDT 1986" 207.It Li "Jan Wed 1989" Ta Li "\&%b \&%a \&%Y" Ta Li "Wed Jan 4 12:19:47 EST 1989" 208.It Li "Fri 9" Ta Li "\&%a \&%H" Ta Li "Fri Sep 26 09:00:00 EDT 1986" 209.It Li "Feb 10:30" Ta Li "\&%b \&%H:\&%S" Ta Li "Sun Feb 1 10:00:30 EST 1987" 210.It Li 10:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 23 10:30:00 EDT 1986" 211.It Li 13:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 22 13:30:00 EDT 1986" 212.El 213.Sh SEE ALSO 214.Xr ctime 3 , 215.Xr localtime 3 , 216.Xr mktime 3 , 217.Xr strftime 3 , 218.Xr strptime 3 , 219.Xr time 3 220.Sh STANDARDS 221The 222.Fn getdate 223function conforms to 224.St -p1003.1-2001 . 225.Sh HISTORY 226The 227.Nm 228function appeared in 229.At V.4 . 230.Sh BUGS 231The 232.Nm 233interface is inherently unsafe for multi-threaded programs or libraries, 234since it returns a pointer to a static variable and uses a global state 235variable. 236