Unix/Linux Go Back    


NetBSD 6.1.5 - man page for getdate (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETDATE(3)			   BSD Library Functions Manual 		       GETDATE(3)

NAME
     getdate, getdate_err -- convert user format date and time

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <time.h>

     struct tm *
     getdate(const char *str);

     extern int getdate_err;

DESCRIPTION
     The getdate() function converts a date or time character string pointed to by str into a
     static tm structure described in tm(3).

     The input string is parsed and interpreted using templates.  A text file containing tem-
     plates is specified by the environment variable DATEMSK.  This should contain the full path
     to the template file.  Lines in the template file represent acceptable date and/or time con-
     version specifications.  These specifications are similar to those given for strptime(3).
     The first line in the template file that matches the input string is used to interpret and
     convert to internal time format.

   Internal Format Conversion
     The following rules apply to converting the input into the internal format.

	   o   If only the weekday is given, the conversion assumes today when the weekday
	       matches today or the first future matching weekday.

	   o   If only the month and no year is given, the conversion assumes the current month
	       when the month matches or the first future matching month.  The first day of the
	       month is assumed if no day is given.

	   o   If only the year is given, the values of the tm_mon, tm_mday, tm_wday, tm_yday,
	       and tm_isdst members of the returned struct tm are unspecified.

	   o   If the century is given, but the year within the century is not given, the conver-
	       sion assumes the current year.

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

	   o   If no date is given, the conversion assumes today when the given hour is greater
	       than the current hour and tomorrow when the given hour is less.

	   o   If %Z is being scanned, then the broken-down time is based on the the current time
	       of the matched timezone and not the current runtime environment timezone.

RETURN VALUES
     If successful, the getdate() function returns a pointer to a static tm structure containing
     the broken-down time.  Otherwise, a null pointer is returned and getdate_err is set to indi-
     cate the error.

     The variable getdate_err can have the following values:

     1	  DATEMSK environment variable is null or undefined.

     2	  Cannot open the template file for reading.

     3	  Get file status failed for template file.

     4	  Template file is not a regular file.

     5	  Encountered an error while reading the template file.

     6	  Cannot allocate memory.

     7	  Input string does not match any line in the template file.

     8	  Input string is invalid (for example February 31) or could not be represented in a
	  time_t.

ENVIRONMENT
     DATEMSK  The full path to the text file containing the templates for acceptable date and/or
	      time conversions.

FILES
     /usr/share/examples/getdate/datemsk.template
	      An example template file that could be specified via the DATEMSK environment vari-
	      able.

EXAMPLES
     The following example shows the possible contents of a template file:

	   %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 for the above template:

	   10/1/87 4 PM
	   Friday
	   Firday September 18, 1987, 10:30:30
	   24,9,1986 10:30
	   at monday the 1st of december in 1986
	   run job at 3 PM, december 2nd

     The following examples show how local data and time specification can be defined in the tem-
     plate.

	   Input String    Line in Template
	   11/27/86	   %m/%d/%y
	   27.11.86	   %d.%m/%y
	   86-11-27	   %y-%m-%d
	   Friday 12:00:00 %A %H:%M:%S

     The following examples illustrate the Internal Format Conversion rules given that the cur-
     rent date is Mon Sep 22 12:19:47 EDT 1986 and the LC_TIME environment variable is set to the
     default C locale.

	   Input String    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		       Sun 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 1987
	   Sep Mon	   %b %a	       Mon Sep	1 12:19:47 EDT 1986
	   Jan Fri	   %b %a	       Fri Jan	2 12:19:47 EDT 1987
	   Dec Mon	   %b %a	       Mon Dec	1 12:19:47 EDT 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	       Tue Sep 22 13:30:00 EDT 1986

SEE ALSO
     ctime(3), localtime(3), mktime(3), strftime(3), strptime(3), time(3)

STANDARDS
     The getdate() function conforms to IEEE Std 1003.1-2001 (``POSIX.1'').

HISTORY
     The getdate function appeared in AT&T System V Release 4 UNIX.

BUGS
     The getdate interface is inherently unsafe for multi-threaded programs or libraries, since
     it returns a pointer to a static variable and uses a global state variable.

BSD					  April 14, 2011				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:20 PM.