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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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 inte-
	     ger as a decimal number [1,99]); single digits are	preceded by 0;
	     see standards(5). If used without the %y specifier,  this	format
	     specifier	will  assume the current year offset in	whichever cen-
	     tury is specified.	The only valid years are between 1902-2037.

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

       %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  required.

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

       %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  sec-
	     ond.

       %t    Any white space.

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

       %U    Week  number  of the year as a decimal number [0,53], with	Sunday
	     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	Monday
	     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 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, 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
       exist in	the current locale,  the behavior  be  as  if  the  unmodified
       conversion specification	were used.

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

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

       %Ex   Locale's alternative date representation.

       %EX   Locale's alternative time representation.

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

       %EY   Full alternative year representation.

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

       %Oe   Same as %Od.

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

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

       %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 alternative
	     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	representation
	     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
       examples	 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	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       ctype(3C),  mktime(3C),	setlocale(3C),	 strftime(3C),	 strptime(3C),
       attributes(5), environ(5), standards(5)

SunOS 5.9			  5 Oct	1999			   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.9>

home | help