[BACK]Return to getdate.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/getdate.3, Revision 1.10

1.10    ! wiz         1: .\"    $NetBSD: getdate.3,v 1.9 2018/02/07 11:16:05 pgoyette Exp $
1.1       ginsbach    2: .\"
1.3       khorben     3: .\" Copyright (c) 2009, 2011, 2012, The NetBSD Foundation.
1.1       ginsbach    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: .\"
1.9       pgoyette   30: .Dd February 7, 2018
1.1       ginsbach   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
1.5       uwe        52: .Vt tm
1.2       jruoho     53: structure described in
                     54: .Xr tm 3 .
1.1       ginsbach   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
1.5       uwe        86: .Vt "struct tm"
1.1       ginsbach   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
1.9       pgoyette  100: is being scanned, then the broken-down time is based on the
1.1       ginsbach  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
1.5       uwe       108: .Vt tm
1.1       ginsbach  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
1.5       uwe       134: Input string is invalid (for example, February 31)
1.1       ginsbach  135: or could not be represented in a
1.5       uwe       136: .Vt time_t .
1.1       ginsbach  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
1.3       khorben   171: Friday September 18, 1987, 10:30:30
1.1       ginsbach  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.
1.4       uwe       179: .Bl -column -offset indent ".Li Friday 12:00:00" ".Sy Line in Template"
1.1       ginsbach  180: .It Sy "Input String" Ta Sy "Line in Template"
                    181: .It Li 11/27/86 Ta Li \&%m/\&%d/\&%y
1.6       uwe       182: .It Li 27.11.86 Ta Li \&%d.\&%m.\&%y
1.1       ginsbach  183: .It Li 86-11-27 Ta Li \&%y-\&%m-\&%d
1.4       uwe       184: .It Li "Friday 12:00:00" Ta Li "\&%A \&%H:\&%M:\&%S"
1.1       ginsbach  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.
1.4       uwe       193: .Bl -column -offset indent ".Li Jan Wed 1989" ".Sy Line in Template" ".Sy Date"
1.1       ginsbach  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"
1.7       uwe       197: .It Li Fri Ta Li \&%a Ta Li "Fri Sep 26 12:19:47 EDT 1986"
1.1       ginsbach  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"
1.7       uwe       200: .It Li December Ta Li \&%B Ta Li "Mon Dec  1 12:19:47 EST 1986"
1.1       ginsbach  201: .It Li "Sep Mon" Ta Li "\&%b %a" Ta Li "Mon Sep  1 12:19:47 EDT 1986"
1.8       uwe       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"
1.1       ginsbach  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.

CVSweb <webmaster@jp.NetBSD.org>