1.\" $NetBSD: getdate.3,v 1.1 2009/05/14 02:37:36 ginsbach 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 May 8, 2009 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. 54.Pp 55The input string is parsed and interpreted using templates. 56A text file containing templates is specified by the 57environment variable 58.Ev DATEMSK . 59This should contain the full path to the template file. 60Lines in the template file represent acceptable date and/or time 61conversion specifications. 62These specifications are similar to those given for 63.Xr strptime 3 . 64The first line in the template file that matches the input string 65is used to interpret and convert to internal time format. 66.Ss Internal Format Conversion 67The following rules apply to converting the input into the internal format. 68.Bl -bullet -offset indent 69.It 70If only the weekday is given, the conversion assumes today when the 71weekday matches today or the first future matching weekday. 72.It 73If only the month and no year is given, the conversion assumes the 74current month when the month matches or the first future matching month. 75The first day of the month is assumed if no day is given. 76.It 77If only the year is given, the values of the 78.Fa tm_mon , 79.Fa tm_mday , 80.Fa tm_wday , 81.Fa tm_yday , 82and 83.Fa tm_isdst 84members of the returned 85.Va "struct tm" 86are unspecified. 87.It 88If the century is given, but the year within the century is not given, 89the conversion assumes the current year. 90.It 91If no hour, minute, and second are given, the conversion assumes 92the current hour, minute, and second. 93.It 94If no date is given, the conversion assumes today when the given hour 95is greater than the current hour and tomorrow when the given hour is less. 96.It 97If 98.Cm \&%Z 99is being scanned, then the broken-down time is based on the the 100current time of the matched timezone and not the current runtime 101environment timezone. 102.El 103.Sh RETURN VALUES 104If successful, the 105.Fn getdate 106function returns a pointer to a static 107.Va tm 108structure containing the broken-down time. 109Otherwise, a null pointer is returned and 110.Va getdate_err 111is set to indicate the error. 112.Pp 113The variable 114.Va getdate_err 115can have the following values: 116.Bl -tag -width NNN 117.It 1 118.Ev DATEMSK 119environment variable is null or undefined. 120.It 2 121Cannot open the template file for reading. 122.It 3 123Get file status failed for template file. 124.It 4 125Template file is not a regular file. 126.It 5 127Encountered an error while reading the template file. 128.It 6 129Cannot allocate memory. 130.It 7 131Input string does not match any line in the template file. 132.It 8 133Input string is invalid 134.Pq for example February 31 135or could not be represented in a 136.Va 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 171Firday 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.Pp 180.Bl -column -offset indent ".Sy Input String" ".Sy Line in Template" 181.It Sy "Input String" Ta Sy "Line in Template" 182.It Li 11/27/86 Ta Li \&%m/\&%d/\&%y 183.It Li 27.11.86 Ta Li \&%d.\&%m/\&%y 184.It Li 86-11-27 Ta Li \&%y-\&%m-\&%d 185.It Li "Friday 12:00:00" Ta "\&%A \&%H:\&%M:\&%S" 186.El 187.Pp 188The following examples illustrate the Internal Format Conversion rules 189given that the current date is 190.Li "Mon Sep 22 12:19:47 EDT 1986" 191and the 192.Ev LC_TIME 193environment variable is set to the default C locale. 194.Pp 195.Bl -column -offset indent ".Sy Input String" ".Sy Line in Template" ".Sy Date" 196.It Sy Input String Ta Sy Line in Template Ta Sy Date 197.It Li Mon Ta Li \&%a Ta Li "Mon Sep 22 12:19:47 EDT 1986" 198.It Li Sun Ta Li \&%a Ta Li "Sun Sep 28 12:19:47 EDT 1986" 199.It Li Fri Ta Li \&%a Ta Li "Sun Sep 26 12:19:47 EDT 1986" 200.It Li September Ta Li \&%B Ta Li "Mon Sep 1 12:19:47 EDT 1986" 201.It Li January Ta Li \&%B Ta Li "Thu Jan 1 12:19:47 EST 1987" 202.It Li December Ta Li \&%B Ta Li "Mon Dec 1 12:19:47 EST 1987" 203.It Li "Sep Mon" Ta Li "\&%b %a" Ta Li "Mon Sep 1 12:19:47 EDT 1986" 204.It Li "Jan Fri" Ta Li "\&%b %a" Ta Li "Fri Jan 2 12:19:47 EDT 1987" 205.It Li "Dec Mon" Ta Li "\&%b %a" Ta Li "Mon Dec 1 12:19:47 EDT 1986" 206.It Li "Jan Wed 1989" Ta Li "\&%b \&%a \&%Y" Ta Li "Wed Jan 4 12:19:47 EST 1989" 207.It Li "Fri 9" Ta Li "\&%a \&%H" Ta Li "Fri Sep 26 09:00:00 EDT 1986" 208.It Li "Feb 10:30" Ta Li "\&%b \&%H:\&%S" Ta Li "Sun Feb 1 10:00:30 EST 1987" 209.It Li 10:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 23 10:30:00 EDT 1986" 210.It Li 13:30 Ta Li "\&%H:\&%M" Ta Li "Tue Sep 22 13:30:00 EDT 1986" 211.El 212.Sh SEE ALSO 213.Xr ctime 3 , 214.Xr localtime 3 , 215.Xr mktime 3 , 216.Xr strftime 3 , 217.Xr strptime 3 , 218.Xr time 3 219.Sh STANDARDS 220The 221.Fn getdate 222function conforms to 223.St -p1003.1-2001 . 224.Sh HISTORY 225The 226.Nm 227function appeared in 228.At V.4 . 229.Sh BUGS 230The 231.Nm 232interface is inherently unsafe for multi-threaded programs or libraries, 233since it returns a pointer to a static variable and uses a global state 234variable. 235