getdate(3)						     Library Functions Manual							getdate(3)

NAME

       getdate, getdate_r - Convert formatted string into time/date structure

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include<time.h>

       struct tm *getdate(
	       const char *string);

       The following function declarations do not conform to current standards and are supported only for backward compatibility:

       #include<time.h>

       struct tm *getdate(
	       char *string);

       struct tm *getdate_r(
	       char *string,
	       struct tm *ptr,
	       int *getdate_err);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       getdate():  XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Points to the user-definable date and/or time specifications.  Points to a time structure.  Points to the local getdate_err.

DESCRIPTION

       The  getdate() function fills a struct tm based on a combination of the supplied string argument and the template file of allowable formats
       for that argument.

       The template file is obtained from the DATEMSK environment variable.  As the pathname is passed to fopen(), it must either be a fully qual-
       ified pathname, or must refer to a file in the current directory whenever getdate() is called.

       The template file is read line by line, and each line is parsed against the argument string in an attempt to make a match.  All comparisons
       are made without regard to case. A matching template line will result in a valid struct tm being filled in and returned. In the event  that
       no match is found, an error is returned in getdate_err.

       Each  line of the template file provides a possible format to match against the input string.  The format is specified by combining special
       time/date specifier characters preceded by % to indicate the particular time/date functions desired.

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

       The following field descriptors are supported: Literal % character Abbreviated weekday name Full weekday name Abbreviated month	name  Full
       month  name  Locale's appropriate date and time representation Day of month: 1 through 31, with optional leading zero Date string formatted
       as %m/%d/%y Same as %d.	Abbreviated month name **Same as %b.????????????  Hour: 00 through 23 Hour: 01 through 12 Month number: 01 through
       12  Minute:  00	through 59 Literal newline character 
 Locale's equivalent to AM or PM string Locale's appropriate representation of time
       (formatted as %I:%M:%S %p in the POSIX locale).	Time formatted as %H:%M Seconds: 00 through 61.  Leap seconds, through the  use  of  algo-
       rithms,	are  allowed  but are not predictable.	Whitespace up through literal tab Locale's appropriate representation of time in AM and PM
       notation (%H:%M:%S in the POSIX locale).  Weekday number: 0 (Sunday) through 6 (Saturday) Date formatted as specified by locale	Time  for-
       matted  as  specified  by locale Year (excluding century).  When a century is not otherwise specified (for example, with %C), values in the
       range 69-99 refer to years in the twentieth century (1969 to 1999, inclusive); values in the range 00-68 refer to years in the twenty-first
       century	(2000  to  2068, inclusive).  Year (including century) as ccyy (for example, 1996) 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() expects, an invalid input specification error will result.  The
       getdate() function calculates an expected time zone based on information supplied to the function (such as the hour, day, and month).

       If  the string parameter specifies the date and time incompletely, the following rules apply: If %Z is being scanned, getdate() initializes
       the broken-down time to be the current time in the scanned time zone.  Otherwise, it initializes the broken-down time based on the  current
       local  time  as if localtime() had been called.	If a year is specified alone, the remainder of the date defaults to January 1.	If a month
       is specified without a day of the month or day of the week, the next month matching that month is used, starting with  the  current  month.
       The  year  advances  if	the matching month is beyond the current year.	The day of the month defaults to the 1st.  If a day of the week is
       specified, the next date matching that day is used, starting with the current day.  The month advances if the matching day  is  beyond  the
       end  of	the  current  month.  The year may advance similarly.  In cases 2, 3 and 4, the time of day is not altered unless it is explicitly
       specified.  If time alone is specified, the date defaults to today (the current day), unless the time specified is earlier  than  now  (the
       current time), in which case the date defaults to tomorrow.

RETURN VALUES

       Upon  successful completion, the getdate() function returns a pointer to a struct tm. Otherwise, it returns a null pointer and the external
       variable getdate_err is set to indicate the error.

       Upon successful completion, the getdate_r function returns pointer struct tm. Otherwise, NULL is returned and the int value pointed  to	by
       the getdate_err pointer is set to indicate the error.

ERRORS

       If an error is detected, getdate() will return NULL and set the error number in getdate_err.  The possible error numbers and their meanings
       are listed below.  The DATEMSK environment variable is null or undefined.  The template file cannot be opened for reading.  Failed  to  get
       file  status information.  The template file is not a regular file.  An I/O error occurred while reading the template file.  Memory alloca-
       tion failed (not enough memory available).  The template does not have a line that matches the input.   Invalid	input  specification  (for
       example,  February  31).   A time is specified that cannot be represented in a time_t (representing the time in seconds since 00:00:00 UTC,
       January 1, 1970).

APPLICATION USAGE

       Applications should use %Y (4-digit years) instead of %y (2-digit years).

RELATED INFORMATION

       Functions: ctime(3), ctype(3), setlocale(3), strftime(3)

       Standards: standards(5) delim off

																	getdate(3)