getdate(3)                                                   getdate(3)

  getdate()

  NAME

    getdate() - convert user format date and time

  SYNOPSIS

    #include 

    struct tm *getdate(const char *string)

  DESCRIPTION

    The getdate(3) function converts a string representation of a date or time
    into a broken-down time.

    The external variable or macro getdate_err is used by getdate(3) 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 are supported; for names, case is
    not important:

    %a
        The day of the week in the current locale, in the abbreviated name
        form.

    %A
        The day of the week in the current locale, in the full name form.

    %b
        The month in the current locale, in the abbreviated name form.

    %B
        The month in the current locale, in the full name form.

    %c
        The appropriate date and time representation for the locale.

    %C
        The century number as a number from 0-99. Leading zeroes are permitted
        but not required.

    %d
        The day of the month as a number from 1-31. Leading zeroes are
        permitted but not required.

    %D
        Equivalent to %m/%d/%y.

    %e
        The same as %d.

    %h
        The same as %b.

    %H
        The hour in a 24-hour clock (a number from 0-23). Leading zeroes are
        permitted but not required.

    %I
        The hour in a 12-hour clock (a number from 1-12). Leading zeroes are
        permitted but not required.

    %j
        The day of the year as a number from 1-366. Leading zeroes are
        permitted but not required.

    %m
        The month as a number from 1-12. Leading zeroes are permitted but not
        required.

    %M
        The minute of the hour as a number from 0-59. Leading zeroes are
        permitted but not required.

    %n
        Any white space.

    %p
        The equivalent of a.m. or p.m. in the current locale.

    %r
        is the 12-hour clock time using the AM/PM notation of the current
        locale, if t_fmt_ampm is not an empty string in the LC_TIME portion of
        the current locale. In the POSIX locale, this will be equivalent to
        %I:%M:%S %p.

    %R
        The time in the format %H:%M.

    %S
        The seconds of the current minute as a number from 0-61. Leading
        zeroes are permitted but not required.

    %t
        Any white space.

    %T
        The time, equivalent to %H:%M:%S.

    %U
        The week number of the year, as a decimal number in the range 00-53.
        Sunday is considered the first day of the week. Leading zeroes are
        permitted but not required.

    %w
        The week day as a number in the range 0-6, where 0 represents Sunday.
        Leading zeroes are permitted but not required.

    %W
        Like %U, but Monday is considered the first day of the week. The week
        number of the year, as a decimal number in the range 00-53. Leading
        zeroes are permitted but not required.

    %x
        The date in the format of the current locale.

    %X
        The time, in the format of the current locale.

    %y
        The year within the century, as a digit from 00-99. If no century is
        specified, values from 69-99 refer to the twentieth century (that is,
        1969-1999), and values from 00-68 refer to years in the twenty-first
        century (the years 2000 to 2068). Sunday is considered the first day
        of the week. Leading zeroes are permitted but not required.

    %Y
        The year, including the century, such as 2001 or 1984.

    %Z
        Time zone name or no characters if no time zone exists. If the time
        zone supplied by %Z is not the time zone that getdate(3) expects, an
        invalid input specification error will result. The getdate(3) function
        calculates an expected time zone based on information supplied to the
        function (such as the hour, day, and month).

    %%
        A per cent character.

    Some of the directives can be modified by the characters E and O to
    indicate that they use an alternative format or specification. (For
    locales where this alternative specification doesn't exist, getdate(3)
    behaves as if the modifying E or O weren't present.)

    %Ec
        The alternative appropriate representative for the date and time.

    %EC
        The name of the base year (or time period) in the alternative
        representation for the locale.

    %Ex
        The alternative date representation for the locale.

    %EX
        The alternative time representation for the locale.

    %Ey
        The offset from the year (%EC) in the alternative representation of
        the year.

    %EY
        The full year representation in the locale's alternative
        representation.

    %Od
        The day of the month in the alternative representation of the locale.
        Leading zeroes are permitted but not required.

    %Oe
        The same as %Od.

    %OH
        The hour in the 24-hour clock using the alternative numeric symbols of
        the locale.

    %OI
        The hour in the 12-hour clock using the alternative numeric symbols of
        the locale.

    %Om
        The month using the alternative numeric symbols of the locale.

    %OM
        The minutes using the alternative numeric symbols of the locale.

    %OS
        The seconds using the alternative numeric symbols of the locale.

    %OU
        The week of the year as a number, using the alternative numeric
        symbols of the locale. Sunday is considered the first day of the week.

    %Ow
        The day of the week as a number using the alternative numeric symbols
        of the locale. Sunday is considered day 0.

    %OW
        The week of the year as a number, using the alternative numeric
        symbols of the locale. Monday is considered the first day of the week.

    %Oy
        The year, offset from %C, using the alternative numeric symbols of the
        locale.

  RETURN VALUES

    If the getdate(3) is successful it returns a struct tm pointer to tm. On
    failure, getdate(3) returns NULL and sets the variable getdate_err to
    indicate the error.

  ERRORS

    The getdate() function will 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 can not be represented in a time_t (representing the
        time in seconds since 00:00:00 UTC, January 1, 1970).

  SEE ALSO

    ctime(3)

    localtime(3)

    setlocale(3)

    strftime(3)

    times(2)

  USAGE NOTES

    The getdate function is not thread safe.

    The getdate function is not async-signal safe.