Man Linux: Main Page and Category List

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 identified  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  calculates  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 specifications.

       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   getdate_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 specifiers 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, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  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 Standard, 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 .