Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getdate(3C)		 Standard C Library Functions		   getdate(3C)

NAME
       getdate - convert user format date and time

SYNOPSIS
       #include	<time.h>

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

DESCRIPTION
       The  getdate() function converts	user-definable date and/or time	speci-
       fications pointed to by string to a tm structure. The tm	 structure  is
       defined in the <time.h> header.

       User-supplied  templates	 are  used  to	parse  and interpret the input
       string.	The templates are  text	files created by the user and  identi-
       fied  via  the  environment variable DATEMSK. Each line in the template
       represents an acceptable	date and/or time specification using   conver-
       sion  specifications  similar  to  those	used by	strftime(3C) and strp-
       time(3C).  Dates	before 1902 and	after 2037 are illegal.	The first line
       in the template that matches the	input specification is used for	inter-
       pretation and conversion	into  the internal time	format.

   Conversion Specifications
       The following conversion	specifications are supported:

       %%	Same as	%.

       %a	Locale's abbreviated weekday name.

       %A	Locale's full weekday name.

       %b	Locale's abbreviated month name.

       %B	Locale's full month name.

       %c	Locale's appropriate date and time representation.

       %C	Century	number (the year divided by 100	and  truncated	to  an
		integer	 as  a	decimal	number [1,99]);	single digits are pre-
		ceded by 0; see	standards(5). If used without  the  %y	speci-
		fier,  this format specifier will assume the current year off-
		set in whichever century is specified. The  only  valid	 years
		are between 1902-2037.

       %d	day  of	 month	[01,31]; leading zero is permitted but not re-
		quired.

       %D	Date as	%m/%d/%y.

       %e	Same as	%d.

       %h	Locale's abbreviated month name.

       %H	Hour (24-hour clock) [0,23]; leading zero is permitted but not
		required.

       %I	Hour (12-hour clock) [1,12]; leading zero is permitted but not
		required.

       %j	Day number of the year [1,366];	leading	 zeros	are  permitted
		but not	required.

       %m	Month  number  [1,12];	leading	 zero is permitted but not re-
		quired.

       %M	Minute [0,59]; leading zero is permitted but not required.

       %n	Any white space.

       %p	Locale's equivalent of either a.m. or p.m.

       %r	Appropriate time representation	in the	12-hour	 clock	format
		with %p.

       %R	Time as	%H:%M.

   SUSv3
       %S	Seconds	 [0,60];  leading  zero	is permitted but not required.
		The range of values  is	[00,60]	rather than [00,59]  to	 allow
		for the	occasional leap	second.

   Default and other standards
       %S	Seconds	 [0,61];  leading  zero	is permitted but not required.
		The range of values  is	[00,61]	rather than [00,59]  to	 allow
		for the	occasional leap	second and even	more occasional	double
		leap second.

       %t	Any white space.

       %T	Time as	%H:%M:%S.

       %U	Week number of the year	as a decimal number [0,53], with  Sun-
		day  as	 the  first day	of the week; leading zero is permitted
		but not	required.

       %w	Weekday	as a decimal number [0,6], with	0 representing Sunday.

       %W	Week number of the year	as a decimal number [0,53], with  Mon-
		day  as	 the  first day	of the week; leading zero is permitted
		but not	required.

       %x	Locale's appropriate date representation.

       %X	Locale's appropriate time representation.

       %y	Year within century. When a century is	not  otherwise	speci-
		fied,  values in the range 69-99 refer to years	in the twenti-
		eth 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, including	the century (for example, 1993).

       %Z	Time zone name or no characters	if no time zone	exists.

   Modified Conversion Specifications
       Some conversion specifications can be modified by the E and O  modifier
       characters  to  indicate	 that  an  alternative format or specification
       should be used rather than the one  normally  used  by  the  unmodified
       specification.  If the alternative format or specification does not ex-
       ist in the current locale,  the behavior	be as if the unmodified	  con-
       version specification were used.

       %Ec	Locale's alternative appropriate date and time representation.

       %EC	Name  of  the  base  year (period) in the locale's alternative
		representation.

       %Ex	Locale's alternative date representation.

       %EX	Locale's alternative time representation.

       %Ey	Offset from %EC	(year only) in the locale's alternative	repre-
		sentation.

       %EY	Full alternative year representation.

       %Od	Day  of	the month using	the locale's alternative  numeric sym-
		bols; leading zeros are	permitted but not required.

       %Oe	Same as	%Od.

       %OH	Hour (24-hour clock) using the	locale's  alternative  numeric
		symbols.

       %OI	Hour  (12-hour	clock)	using the locale's alternative numeric
		symbols.

       %Om	Month using the	locale's alternative numeric symbols.

       %OM	Minutes	using the locale's alternative numeric symbols.

       %OS	Seconds	using the locale's alternative numeric symbols.

       %OU	Week number of the year	(Sunday	as the first day of the	 week)
		using the locale's alternative numeric symbols.

       %Ow	Number	of the weekday (Sunday=0) using	the  locale's alterna-
		tive numeric symbols.

       %OW	Week number of the year	(Monday	as the first day of the	 week)
		using the locale's alternative numeric symbols.

       %Oy	Year (offset from %C) in the locale's alternative  representa-
		tion and using the locale's alternative	numeric	symbols.

   Internal Format Conversion
       The following rules are applied for converting the input	 specification
       into the	internal format:

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

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

	 o  If	only  the  year	 is  given, the	values of the tm_mon, tm_mday,
	    tm_yday, tm_wday, and tm_isdst members of the returned  tm	struc-
	    ture are not specified.

	 o  If	the  century  is given,	but the	year within the	century	is not
	    given, the current year within the century is assumed.

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

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

   General Specifications
       A conversion specification that is an ordinary character	is executed by
       scanning	 the  next character from the buffer. If the character scanned
       from the	buffer differs from the	one comprising the conversion specifi-
       cation, the specification fails,	and the	differing and subsequent char-
       acters remain unscanned.

       A series	of conversion specifications composed of %n, %t,  white	 space
       characters,  or any combination is executed by scanning up to the first
       character that is not white space (which	remains	unscanned),  or	 until
       no more characters can be scanned.

       Any  other  conversion specification is executed	by scanning characters
       until  a	 character  matching  the  next	 conversion  specification  is
       scanned,	or until no more characters can	be scanned.  These characters,
       except the one matching the next	 conversion  specification,  are  then
       compared	to the locale values associated	with the conversion specifier.
       If a match is found, values for the appropriate	tm  structure  members
       are  set	to values corresponding	to the locale information. If no match
       is found, getdate() fails and no	more characters	are scanned.

       The month names,	weekday	names, era names, and alternative numeric sym-
       bols  can  consist  of any combination of upper and lower case letters.
       The user	can request that the input date	or time	specification be in  a
       specific	language by setting the	LC_TIME	category using setlocale(3C).

RETURN VALUES
       If  successful,	getdate()  returns a pointer to	a tm structure;	other-
       wise, it	returns	NULL and sets the global variable getdate_err to indi-
       cate  the  error.  Subsequent  calls to getdate() alter the contents of
       getdate_err.

       The following is	a complete list	of the	getdate_err settings and their
       meanings:

       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 error is encountered	while reading the template file.

       6	The malloc() function failed (not enough memory	is available).

       7	There is no line in the	template that matches the input.

       8	The input specification	is invalid (for	example, February 31).

USAGE
       The  getdate()  function	 makes explicit	use of macros described	on the
       ctype(3C) manual	page.

EXAMPLES
       Example 1: Examples of the getdate() function.

       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

       The following are examples of valid input specifications	for the	 above
       template:

       getdate("10/1/87	4 PM")
       getdate("Friday")
       getdate("Friday September 19 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 LANG environment	variable is set	to  de (German), the following
       is valid:

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

       Local time and date specification are also supported. The following ex-
       amples show 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		   |
       +-----------------------------+-----------------------------+

       The following examples illustrate the Internal Format Conversion	rules.
       Assume  that  the  current date is Mon Sep 22 12:19:47 EDT 1986 and the
       LANG environment	variable is not	set.

       +---------------+----------------+-----------------------------+
       |    Input      |Template Line	|	     Date	      |
       |Mon	       |%a		|Mon Sep 22 12:19:48 EDT 1986 |
       |Sun	       |%a		|Sun Sep 28 12:19:49 EDT 1986 |
       |Fri	       |%a		|Fri Sep 26 12:19:49 EDT 1986 |
       |September      |%B		|Mon Sep  1 12:19:49 EDT 1986 |
       |January	       |%B		|Thu Jan  1 12:19:49 EST 1987 |
       |December       |%B		|Mon Dec  1 12:19:49 EDT 1986 |
       |Sep Mon	       |%b %a		|Mon Sep  1 12:19:50 EDT 1986 |
       |Jan Fri	       |%b %a		|Fri Jan  2 12:19:50 EST 1987 |
       |Dec Mon	       |%b %a		|Mon Dec  1 12:19:50 EST 1986 |
       |Jan Wed	1989   |%b %a %Y	|Wed Jan  4 12:19:51 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 |
       +---------------+----------------+-----------------------------+

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       ctype(3C), mktime(3C), setlocale(3C), strftime(3C),  strptime(3C),  at-
       tributes(5), environ(5),	standards(5)

SunOS 5.10			  1 Nov	2003			   getdate(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getdate&sektion=3c&manpath=SunOS+5.10>

home | help