Man Pages

getdate(3p) - phpMan getdate(3p) - phpMan

Command: man perldoc info search(apropos)  


GETDATE(3P)                POSIX Programmer's Manual               GETDATE(3P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

NAME
       getdate - convert user format date and time

SYNOPSIS
       #include <time.h>

       struct tm *getdate(const char *string);


DESCRIPTION
       The getdate() function shall convert a string representation of a date or time into a broken-down time.

       The external variable or macro getdate_err is used by getdate() to return error values.

       Templates  are used to parse and interpret the input string. The templates are contained in a text file identi-
       fied by the environment variable DATEMSK.  The DATEMSK variable should be set to indicate the full pathname  of
       the  file  that  contains the templates. The first line in the template that matches the input specification is
       used for interpretation and conversion into the internal time format.

       The following conversion specifications shall be supported:

       %%     Equivalent to % .

       %a     Abbreviated weekday name.

       %A     Full weekday name.

       %b     Abbreviated month name.

       %B     Full month name.

       %c     Locale's appropriate date and time representation.

       %C     Century number [00,99]; leading zeros are permitted but not required.

       %d     Day of month [01,31]; the leading 0 is optional.

       %D     Date as %m / %d / %y .

       %e     Equivalent to %d .

       %h     Abbreviated month name.

       %H     Hour [00,23].

       %I     Hour [01,12].

       %m     Month number [01,12].

       %M     Minute [00,59].

       %n     Equivalent to <newline>.

       %p     Locale's equivalent of either AM or PM.

       %r     The locale's appropriate representation of time in AM and PM notation.  In the POSIX locale, this  shall
              be equivalent to %I : %M : %S %p .

       %R     Time as %H : %M .

       %S     Seconds  [00,60]. The range goes to 60 (rather than stopping at 59) to allow positive leap seconds to be
              expressed. Since leap seconds cannot be predicted by any algorithm, leap second data must come from some
              external source.

       %t     Equivalent to <tab>.

       %T     Time as %H : %M : %S .

       %w     Weekday number (Sunday = [0,6]).

       %x     Locale's appropriate date representation.

       %X     Locale's appropriate time representation.

       %y     Year  within century. When a century is not otherwise specified, values in the range [69,99] shall refer
              to years 1969 to 1999 inclusive, and values in the range [00,68] shall  refer  to  years  2000  to  2068
              inclusive.

       Note:
              It  is  expected  that  in  a future version of IEEE Std 1003.1-2001 the default century inferred from a
              2-digit year will change. (This would apply to all commands accepting a 2-digit year as input.)


       %Y     Year as "ccyy" (for example, 2001).

       %Z     Timezone name or no characters if no timezone exists. If the timezone supplied by %Z is not the timezone
              that getdate() expects, an invalid input specification error shall result. The getdate() function calcu-
              lates an expected timezone based on information supplied to the function (such as  the  hour,  day,  and
              month).


       The match between the template and input specification performed by getdate() shall be case-insensitive.

       The  month  and  weekday  names  can consist of any combination of upper and lowercase letters. The process can
       request that the input date or time specification be in a specific language by  setting  the  LC_TIME  category
       (see setlocale()).

       Leading  zeros  are not necessary for the descriptors that allow leading zeros. However, at most two digits are
       allowed for those descriptors, including leading zeros. Extra whitespace in either  the  template  file  or  in
       string shall be ignored.

       The results are undefined if the conversion specifications %c, %x, and %X include unsupported conversion speci-
       fications.

       The following rules apply for converting the input specification into the internal format:

        * If %Z is being scanned, then getdate() shall initialize the broken-down time to be the current time  in  the
          scanned  timezone. Otherwise, it shall initialize the broken-down time based on the current local time as if
          localtime() had been called.


        * If only the weekday is given, the day chosen shall be the day, starting  with  today  and  moving  into  the
          future, which first matches the named day.


        * If  only  the  month  (and no year) is given, the month chosen shall be the month, starting with the current
          month and moving into the future, which first matches the named month. The first day of the month  shall  be
          assumed if no day is given.


        * If no hour, minute, and second are given, the current hour, minute, and second shall be assumed.


        * If  no  date is given, the hour chosen shall be the hour, starting with the current hour and moving into the
          future, which first matches the named hour.


       If a conversion specification in the DATEMSK file does not correspond to one of the  conversion  specifications
       above, the behavior is unspecified.

       The  getdate()  function need not be reentrant. A function that is not required to be reentrant is not required
       to be thread-safe.

RETURN VALUE
       Upon successful completion, getdate() shall return a pointer to a struct tm. Otherwise, it shall return a  null
       pointer and set getdate_err to indicate the error.

ERRORS
       The  getdate()  function  shall fail in the following cases, setting getdate_err to the value shown in the list
       below. Any changes to errno are unspecified.

        1. The DATEMSK environment variable is null or undefined.


        2. The template file cannot be opened for reading.


        3. Failed to get file status information.


        4. The template file is not a regular file.


        5. An I/O error is encountered while reading the template file.


        6. Memory allocation failed (not enough memory available).


        7. There is no line in the template that matches the input.


        8. Invalid input specification. For example, February 31; or a time is specified that cannot be represented in
           a time_t (representing the time in seconds since the Epoch).


       The following sections are informative.

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


           %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


        2. The following are examples of valid input specifications for the template in Example 1:


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

       If  the  LC_TIME  category  is  set to a German locale that includes freitag as a weekday name and oktober as a
       month name, the following would be valid:


              getdate("freitag den 10. oktober 1986 10.30 Uhr");


        3. The following example shows how local date and time specification can be defined in the template:

                                          Invocation                   Line in Template
                                          getdate("11/27/86")          %m/%d/%y
                                          getdate("27.11.86")          %d.%m.%y
                                          getdate("86-11-27")          %y-%m-%d
                                          getdate("Friday 12:00:00")   %A %H:%M:%S


        4. The following examples help to illustrate the above rules assuming that the current  date  is  Mon  Sep  22
           12:19:47 EDT 1986 and the LC_TIME category is set to the default C locale:

                                  Input         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             Mon Sep 22 13:30:00 EDT 1986


APPLICATION USAGE
       Although  historical  versions  of  getdate()  did not require that <time.h> declare the external variable get-
       date_err, this volume of IEEE Std 1003.1-2001 does require it. The standard developers  encourage  applications
       to remove declarations of getdate_err and instead incorporate the declaration by including <time.h>.

       Applications should use %Y (4-digit years) in preference to %y (2-digit years).

RATIONALE
       In  standard locales, the conversion specifications %c, %x, and %X do not include unsupported conversion speci-
       fiers and so the text regarding results being undefined is not a problem in that case.

FUTURE DIRECTIONS
       None.

SEE ALSO
       ctime(), localtime(), setlocale(), strftime(), times(), the Base Definitions  volume  of  IEEE Std 1003.1-2001,
       <time.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  Issue  6,  Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The
       Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Stan-
       dard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                          GETDATE(3P)