👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for getdate (linux section 3posix)

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

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 bro-
       ken-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 posi-
	      tive 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 accept-
	      ing 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  lan-
       guage 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  white-
       space in either the template file or in string shall be ignored.

       The results are undefined if the conversion specifications %c , %x , and %X include unsup-
       ported 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 con-
       version specifications above, the behavior is unspecified.

       The getdate() function need not be reentrant. A function that is not required to be  reen-
       trant 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 exter-
       nal variable getdate_err, this volume of IEEE Std 1003.1-2001 does require it.  The  stan-
       dard  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  unsup-
       ported  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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       GETDATE(P)


All times are GMT -4. The time now is 06:10 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password