*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> getdate (3c)              


getdate(3C)							   getdate(3C)

NAME    [Toc]    [Back]

     getdate - convert user format date	and time

SYNOPSIS    [Toc]    [Back]

     #include <time.h>

     struct tm *getdate	(const char *string);
     extern int	getdate_err;

DESCRIPTION    [Toc]    [Back]

     getdate The getdate 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() 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 field descriptors are supported:

     %%	  same as %

     %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	  same as %d

     %h	  abbreviated month name

     %H	  hour (00-23)

     %I	  hour (01-12)

									Page 1

getdate(3C)							   getdate(3C)

     %m	  month	number (01-12)

     %M	  minute (00-59)

     %n	  same as new line

     %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 is equivalent to %I:%M:%S	%p

     %R	  time as %H:%M

     %S	  seconds (00-61).  Leap seconds are allowed but are not predictable
	  through use of algorithms.

     %t	  same as 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 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).

     %Y	  year as ccyy (for example, 1994)

     %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() 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).

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

     The month and weekday names can consist of	any combination	of upper and
     lower case	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 0's are not necessary for the descriptors that allow leading 0's.
     However, at most two digits are allowed for those descriptors, including
     leading 0's.  Extra whitespace in either the template file	or in string
     is	ignored.

									Page 2

getdate(3C)							   getdate(3C)

     The field descriptors %c, %x, and %X will not be supported	if they
     include unsupported field descriptors.

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

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

	  If only the weekday is given,	today is assumed if the	given day is
	  equal	to the current day and next week if it is less.

	  If only the month is given, the current month	is assumed if the
	  given	month is equal to the current month and	next year if it	is
	  less and no year is given (the first day of month is assumed if no
	  day is given).

	  If no	hour, minute and second	are given the current hour, minute and
	  second are assumed,

	  If no	date is	given, today is	assumed	if the given hour is greater
	  than the current hour	and tomorrow is	assumed	if it is less.

     If	a field	descriptor specification in the	DATEMSK	file does not
     correspond	to one of the field descriptors	above, the behaviour is

RETURN VALUE    [Toc]    [Back]

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

ERRORS    [Toc]    [Back]

     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).

									Page 3

getdate(3C)							   getdate(3C)

     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).

EXAMPLE    [Toc]    [Back]

     Example 1:

     The following example shows the possible contents of a template:


	  %A %B	%d, %Y,	%H:%M:%S



	  %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

     Example 2:

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

	  getdate("10/1/87 4 PM");


	  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

									Page 4

getdate(3C)							   getdate(3C)

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

     Example 3:

     The following examples 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

     Example 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    [Toc]    [Back]

     Although historical versions of getdate() did not require that <time.h>
     declare the external variable getdate_err,	this document does require it.
     The Open Group encourages applications to remove declarations of
     getdate_err and instead incorporate the declaration by including

SEE ALSO    [Toc]    [Back]

     ctime(), ctype(), localtime(), setlocale(), strftime(), times(), <time.h>

									PPPPaaaaggggeeee 5555
[ Back ]
 Similar pages
Name OS Title
strftime OpenBSD format date and time
strftime FreeBSD format date and time
strftime Linux format date and time
strftime NetBSD format date and time
localtime_r NetBSD convert date and time to ASCII
mktime NetBSD convert date and time to ASCII
localtime NetBSD convert date and time to ASCII
strftime Tru64 Convert a date and time to a string
strftime IRIX convert date and time to string
gmtime_r NetBSD convert date and time to ASCII
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service