lib/libc/stdtime/getdate.3

   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
  47 The
  48 .Fn getdate
  49 function converts a date or time character string pointed to by
  50 .Fa str
  51 into a static
  52 .Vt tm
  53 structure described in
  54 .Xr tm 3 .
  55 .Pp
  56 The input string is parsed and interpreted using templates.
  57 A text file containing templates is specified by the
  58 environment variable
  59 .Ev DATEMSK .
  60 This should contain the full path to the template file.
  61 Lines in the template file represent acceptable date and/or time
  62 conversion specifications.
  63 These specifications are similar to those given for
  64 .Xr strptime 3 .
  65 The first line in the template file that matches the input string
  66 is used to interpret and convert to internal time format.
  67 .Ss Internal Format Conversion
  68 The following rules apply to converting the input into the internal format.
  69 .Bl -bullet -offset indent
  70 .It
  71 If only the weekday is given, the conversion assumes today when the
  72 weekday matches today or the first future matching weekday.
  73 .It
  74 If only the month and no year is given, the conversion assumes the
  75 current month when the month matches or the first future matching month.
  76 The first day of the month is assumed if no day is given.
  77 .It
  78 If 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 ,
  83 and
  84 .Fa tm_isdst
  85 members of the returned
  86 .Vt "struct tm"
  87 are unspecified.
  88 .It
  89 If the century is given, but the year within the century is not given,
  90 the conversion assumes the current year.
  91 .It
  92 If no hour, minute, and second are given, the conversion assumes
  93 the current hour, minute, and second.
  94 .It
  95 If no date is given, the conversion assumes today when the given hour
  96 is greater than the current hour and tomorrow when the given hour is less.
  97 .It
  98 If
  99 .Cm \&%Z
 100 is being scanned, then the broken-down time is based on the
 101 current time of the matched timezone and not the current runtime
 102 environment timezone.
 103 .El
 104 .Sh RETURN VALUES
 105 If successful, the
 106 .Fn getdate
 107 function returns a pointer to a static
 108 .Vt tm
 109 structure containing the broken-down time.
 110 Otherwise, a null pointer is returned and
 111 .Va getdate_err
 112 is set to indicate the error.
 113 .Pp
 114 The variable
 115 .Va getdate_err
 116 can have the following values:
 117 .Bl -tag -width NNN
 118 .It 1
 119 .Ev DATEMSK
 120 environment variable is null or undefined.
 121 .It 2
 122 Cannot open the template file for reading.
 123 .It 3
 124 Get file status failed for template file.
 125 .It 4
 126 Template file is not a regular file.
 127 .It 5
 128 Encountered an error while reading the template file.
 129 .It 6
 130 Cannot allocate memory.
 131 .It 7
 132 Input string does not match any line in the template file.
 133 .It 8
 134 Input string is invalid (for example, February 31)
 135 or could not be represented in a
 136 .Vt time_t .
 137 .El
 138 .Sh ENVIRONMENT
 139 .Bl -tag -width DATEMSK
 140 .It Ev DATEMSK
 141 The full path to the text file containing the templates
 142 for 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
 147 An example template file that could be specified via the
 148 .Ev DATEMSK
 149 environment variable.
 150 .El
 151 .Sh EXAMPLES
 152 The 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
 161 at %A the %dst of %B in %Y
 162 run job at %I %p, %B %dnd
 163 %A den %d. %B %Y %H.%M Uhr
 164 .Ed
 165 .Pp
 166 The following are examples of valid input for the above template:
 167 .Pp
 168 .Bd -literal -offset indent -compact
 169 10/1/87 4 PM
 170 Friday
 171 Friday September 18, 1987, 10:30:30
 172 24,9,1986 10:30
 173 at monday the 1st of december in 1986
 174 run job at 3 PM, december 2nd
 175 .Ed
 176 .Pp
 177 The following examples show how local data and time specification can be
 178 defined 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
 187 The following examples illustrate the Internal Format Conversion rules
 188 given that the current date is
 189 .Li "Mon Sep 22 12:19:47 EDT 1986"
 190 and the
 191 .Ev LC_TIME
 192 environment 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
 218 The
 219 .Fn getdate
 220 function conforms to
 221 .St -p1003.1-2001 .
 222 .Sh HISTORY
 223 The
 224 .Nm
 225 function appeared in
 226 .At V.4 .
 227 .Sh BUGS
 228 The
 229 .Nm
 230 interface is inherently unsafe for multi-threaded programs or libraries,
 231 since it returns a pointer to a static variable and uses a global state
 232 variable.