Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


GETDATE(3)                 Library Functions Manual                 GETDATE(3)

NAME
     getdate, getdate_err - convert user format date and time

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <time.h>

     struct tm *
     getdate(const char *str);

     extern int getdate_err;

DESCRIPTION
     The getdate() function converts a date or time character string pointed
     to by str into a static tm structure described in tm(3).

     The input string is parsed and interpreted using templates.  A text file
     containing templates is specified by the environment variable DATEMSK.
     This should contain the full path to the template file.  Lines in the
     template file represent acceptable date and/or time conversion
     specifications.  These specifications are similar to those given for
     strptime(3).  The first line in the template file that matches the input
     string is used to interpret and convert to internal time format.

   Internal Format Conversion
     The following rules apply to converting the input into the internal
     format.

              If only the weekday is given, the conversion assumes today when
               the weekday matches today or the first future matching weekday.

              If only the month and no year is given, the conversion assumes
               the current month when the month matches or the first future
               matching month.  The first day of the month is assumed if no
               day is given.

              If only the year is given, the values of the tm_mon, tm_mday,
               tm_wday, tm_yday, and tm_isdst members of the returned struct
               tm are unspecified.

              If the century is given, but the year within the century is not
               given, the conversion assumes the current year.

              If no hour, minute, and second are given, the conversion
               assumes the current hour, minute, and second.

              If no date is given, the conversion assumes today when the
               given hour is greater than the current hour and tomorrow when
               the given hour is less.

              If %Z is being scanned, then the broken-down time is based on
               the current time of the matched timezone and not the current
               runtime environment timezone.

RETURN VALUES
     If successful, the getdate() function returns a pointer to a static tm
     structure containing the broken-down time.  Otherwise, a null pointer is
     returned and getdate_err is set to indicate the error.

     The variable getdate_err can have the following values:

     1    DATEMSK environment variable is null or undefined.

     2    Cannot open the template file for reading.

     3    Get file status failed for template file.

     4    Template file is not a regular file.

     5    Encountered an error while reading the template file.

     6    Cannot allocate memory.

     7    Input string does not match any line in the template file.

     8    Input string is invalid (for example, February 31) or could not be
          represented in a time_t.

ENVIRONMENT
     DATEMSK  The full path to the text file containing the templates for
              acceptable date and/or time conversions.

FILES
     /usr/share/examples/getdate/datemsk.template
              An example template file that could be specified via the DATEMSK
              environment variable.

EXAMPLES
     The following example shows the possible contents of a template file:

           %m
           %A %B %d, %Y, %H:%M:%S
           %A
           %B
           %m/%d/%y %I %p
           %d,%m,%Y %H:%M
           at %A the %dst of %B in %Y
           run job at %I %p, %B %dnd
           %A den %d. %B %Y %H.%M Uhr

     The following are examples of valid input for the above template:

           10/1/87 4 PM
           Friday
           Friday September 18, 1987, 10:30:30
           24,9,1986 10:30
           at monday the 1st of december in 1986
           run job at 3 PM, december 2nd

     The following examples show how local data and time specification can be
     defined in the template.

           Input String           Line in Template
           11/27/86               %m/%d/%y
           27.11.86               %d.%m.%y
           86-11-27               %y-%m-%d
           Friday 12:00:00        %A %H:%M:%S

     The following examples illustrate the Internal Format Conversion rules
     given that the current date is Mon Sep 22 12:19:47 EDT 1986 and the
     LC_TIME environment variable is set to the default C locale.

           Input String        Line in Template        Date
           Mon                 %a                      Mon Sep 22 12:19:47 EDT
                                                       1986
           Sun                 %a                      Sun Sep 28 12:19:47 EDT
                                                       1986
           Fri                 %a                      Fri Sep 26 12:19:47 EDT
                                                       1986
           September           %B                      Mon Sep  1 12:19:47 EDT
                                                       1986
           January             %B                      Thu Jan  1 12:19:47 EST
                                                       1987
           December            %B                      Mon Dec  1 12:19:47 EST
                                                       1986
           Sep Mon             %b %a                   Mon Sep  1 12:19:47 EDT
                                                       1986
           Jan Fri             %b %a                   Fri Jan  2 12:19:47 EST
                                                       1987
           Dec Mon             %b %a                   Mon Dec  1 12:19:47 EST
                                                       1986
           Jan Wed 1989        %b %a %Y                Wed Jan  4 12:19:47 EST
                                                       1989
           Fri 9               %a %H                   Fri Sep 26 09:00:00 EDT
                                                       1986
           Feb 10:30           %b %H:%S                Sun Feb  1 10:00:30 EST
                                                       1987
           10:30               %H:%M                   Tue Sep 23 10:30:00 EDT
                                                       1986
           13:30               %H:%M                   Tue Sep 22 13:30:00 EDT
                                                       1986

SEE ALSO
     ctime(3), localtime(3), mktime(3), strftime(3), strptime(3), time(3)

STANDARDS
     The getdate() function conforms to IEEE Std 1003.1-2001 ("POSIX.1").

HISTORY
     The getdate function appeared in AT&T System V Release 4 UNIX.

BUGS
     The getdate interface is inherently unsafe for multi-threaded programs or
     libraries, since it returns a pointer to a static variable and uses a
     global state variable.

NetBSD 10.99                   February 7, 2018                   NetBSD 10.99