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

FreeBSD Manual Pages

  
 
  

home | help
CTIME(3V)							     CTIME(3V)

NAME
       ctime,  asctime,	dysize,	gmtime,	localtime, strftime, strptime, timegm,
       timelocal, tzset, tzsetwall - convert date and time

SYNOPSIS
       #include	<time.h>

       char *ctime(clock)
       time_t *clock;

       char *asctime(tm)
       struct tm *tm;

       int dysize(y)
       int y;

       struct tm *gmtime(clock)
       time_t *clock;

       struct tm *localtime(clock)
       time_t *clock;

       int strftime(buf, bufsize, fmt, tm)
       char *buf;
       int bufsize;
       char *fmt;
       struct tm *tm;

       char *strptime(buf, fmt,	tm)
       char *buf;
       char *fmt;
       struct tm *tm;

       time_t timegm(tm)
       struct tm *tm;

       time_t timelocal(tm)
       struct tm *tm;

       void tzset()

       void tzsetwall()

SYSTEM V SYNOPSIS
       In addition to the routines above, the following	variables  are	avail-
       able:

       extern long timezone;

       extern int daylight;

       extern char *tzname[2];

DESCRIPTION
       ctime() converts	a long integer,	pointed	to by clock, to	a 26-character
       string of the form produced by asctime().  It first breaks  down	 clock
       to  a  tm structure by calling localtime(), and then calls asctime() to
       convert that tm structure to a string.

       asctime() converts a time value	contained  in  a  tm  structure	 to  a
       26-character string of the form:

	      Sun Sep 16 01:03:52 1973\n\0

       Each  field  has	 a constant width.  asctime() returns a	pointer	to the
       string.

       dysize()	returns	the number of days in the argument year, either	365 or
       366.  localtime() and gmtime() return pointers to structures containing
       the time, broken	down into various components of	that time  represented
       in a particular time zone.  localtime() breaks down a time specified by
       the value pointed to by the clock argument,  correcting	for  the  time
       zone  and  any  time  zone adjustments (such as Daylight	Savings	Time).
       Before doing so,	localtime() calls tzset() (if  tzset()	has  not  been
       called  in the current process).	 gmtime() breaks down a	time specified
       by the value pointed to by the clock argument into GMT,	which  is  the
       time the	system uses.

       strftime()  converts a time value contained in the tm structure pointed
       to by tm	to a character string in a format specified by fmt.  The char-
       acter  string  is placed	into the array pointed to by buf, which	is as-
       sumed to	contain	room for at least buflen characters.   If  the	result
       contains	 no more than buflen characters, strftime() returns the	number
       of characters produced (not including the terminating null  character).
       Otherwise, it returns zero and the contents of the array	are indetermi-
       nate.  fmt is a character string	that consists of field descriptors and
       text characters,	reminiscent of printf(3V).  Each field descriptor con-
       sists of	a % character followd by another character that	specifies  the
       replacement  for	the field descriptor.  All other characters are	copied
       from fmt	into the result.  The following	 field	descriptors  are  sup-
       ported:

	      %%     same as %

	      %a     day of week, using	locale's abbreviated weekday names

	      %A     day of week, using	locale's full weekday names

	      %b
	      %h     month, using locale's abbreviated month names

	      %B     month, using locale's full	month names

	      %c     date and time as %x %X

	      %C     date and time, in locale's	long-format date and time rep-
		     resentation

	      %d     day of month (01-31)

	      %D     date as %m/%d/%y

	      %e     day of month (1-31;  single  digits  are  preceded	 by  a
		     blank)

	      %H     hour (00-23)

	      %I     hour (00-12)

	      %j     day number	of year	(001-366)

	      %k     hour (0-23; single	digits are preceded by a blank)

	      %l     hour (1-12; single	digits are preceded by a blank)

	      %m     month number (01-12)

	      %M     minute (00-59)

	      %n     same as \n

	      %p     locale's equivalent of AM or PM, whichever	is appropriate

	      %r     time as %I:%M:%S %p

	      %R     time as %H:%M

	      %S     seconds (00-59)

	      %t     same as \t

	      %T     time as %H:%M:%S

	      %U     week  number  of year (01-52), Sunday is the first	day of
		     the week

	      %w     day of week; Sunday is day	0

	      %W     week number of year (01-52), Monday is the	first  day  of
		     the week

	      %x     date, using locale's date format

	      %X     time, using locale's time format

	      %y     year within century (00-99)

	      %Y     year, including century (fore example, 1988)

	      %Z     time zone abbreviation

       The  difference	between	 %U and	%W lies	in which day is	counted	as the
       first day of the	week.  Week number 01 is the first week	with  four  or
       more January days in it.

       strptime()  converts  the  character string pointed to by buf to	a time
       value, which is stored in the tm	structure pointed to by	tm, using  the
       format specified	by fmt.	 A pointer to the character following the last
       character in the	string pointed to by buf is returned.  fmt is a	 char-
       acter  string  that  consists of	field descriptors and text characters,
       reminiscent of scanf(3v).  Each field descriptor	consists of a %	 char-
       acter  followd  by another character that specifies the replacement for
       the field descriptor.  All other	characters are copied  from  fmt  into
       the result.  The	following field	descriptors are	supported:

	      %%     same as %

	      %a
	      %A     day of week, using	locale's weekday names;	either the ab-
		     breviated or full name may	be specified

	      %b
	      %B
	      %h     month, using locale's month names;	either the abbreviated
		     or	full name may be specified

	      %c     date and time as %x %X

	      %C     date and time, in locale's	long-format date and time rep-
		     resentation

	      %d
	      %e     day of month (1-31; leading zeroes	are permitted but  not
		     required)

	      %D     date as %m/%d/%y

	      %H
	      %k     hour  (0-23;  leading  zeroes  are	 permitted but not re-
		     quired)

	      %I
	      %l     hour (0-12; leading zeroes	 are  permitted	 but  not  re-
		     quired)

	      %j     day number	of year	(001-366)

	      %m     month  number (1-12; leading zeroes are permitted but not
		     required)

	      %M     minute (0-59; leading zeroes are permitted	 but  not  re-
		     quired)

	      %p     locale's equivalent of AM or PM

	      %r     time as %I:%M:%S %p

	      %R     time as %H:%M

	      %S     seconds  (0-59;  leading zeroes are permitted but not re-
		     quired)

	      %T     time as %H:%M:%S

	      %x     date, using locale's date format

	      %X     time, using locale's time format

	      %y     year within century (0-99;	leading	zeroes	are  permitted
		     but not required)

	      %Y     year, including century (for example, 1988)

       Case  is	 ignored  when	matching items such as month or	weekday	names.
       The %M, %S, %y, and %Y fields are optional; if they would be matched by
       white  space,  the match	is suppressed and the appropriate field	of the
       tm structure pointed to by tm is	left unchanged.	 If any	of the	format
       items  %d,  %e,	%H, %k,	%I, %l,	%m, %M,	%S, %y,	or %Y are matched, but
       the string that matches them is followed	by white space,	all subsequent
       items  in the format string are skipped up to white space or the	end of
       the format.  The	net result is that, for	example, the  format  %m/%d/%y
       can  be	matched	 by the	string 12/31; the tm_mon and tm_mday fields of
       the tm structure	pointed	to by tm will be set to	 11  and  31,  respec-
       tively, while the tm_year field will be unchanged.

       timelocal()  and	 timegm()  convert  the	 time  specified  by the value
       pointed to by the tm argument to	a time value that represents that time
       expressed as the	number of seconds since	Jan. 1,	1970, 00:00, Greenwich
       Mean Time.  timelocal() converts	a tm structure that  represents	 local
       time,  correcting for the time zone and any time	zone adjustments (such
       as Daylight Savings Time).  Before doing	so, timelocal()	calls  tzset()
       (if tzset() has not been	called in the current process).	 timegm() con-
       verts a tm structure that represents GMT.

       tzset() uses the	value of the environment variable TZ to	set time  con-
       version	information used by localtime().  If TZ	is absent from the en-
       vironment, the an available approximation to local wall clock  time  is
       used by localtime().  If	TZ appears in the environment but its value is
       a null string, Greenwich	Mean Time is used; if TZ  appears  and	begins
       with  a slash, it is used as the	absolute pathname of the tzfile-format
       (see tzfile(5)) file from which to read the  time  conversion  informa-
       tion;  if TZ appears and	begins with a character	other than a slash, it
       is used as a pathname relative to a system time conversion  information
       directory.

       tzsetwall()  sets things	up so that localtime() returns the best	avail-
       able approximation of local wall	clock time.

       Declarations of all the functions and externals,	and the	tm  structure,
       are  in the <time.h> header file.  The structure	(of type) tm structure
       includes	the following fields:

		   int tm_sec;	    /* seconds (0 - 59)	*/
		   int tm_min;	    /* minutes (0 - 59)	*/
		   int tm_hour;	    /* hours (0	- 23) */
		   int tm_mday;	    /* day of month (1 - 31) */
		   int tm_mon;	    /* month of	year (0	- 11) */
		   int tm_year;	    /* year - 1900 */
		   int tm_wday;	    /* day of week (Sunday = 0)	*/
		   int tm_yday;	    /* day of year (0 -	365) */
		   int tm_isdst;    /* 1 if DST	in effect */
		   char	*tm_zone;   /* abbreviation of timezone	name */
		   long	tm_gmtoff;  /* offset from GMT in seconds */

       tm_isdst	is non-zero if Daylight	Savings	Time is	 in  effect.   tm_zone
       points to a string that is the name used	for the	local time zone	at the
       time being converted.  tm_gmtoff	is the offset (in seconds) of the time
       represented  from  GMT,	with positive values indicating	East of	Green-
       wich.

SYSTEM V DESCRIPTION
       The external long variable timezone contains the	 difference,  in  sec-
       onds,  between  GMT  and	 local	standard  time	(in  PST,  timezone is
       8*60*60).  If this difference is	not a constant,	timezone will  contain
       the value of the	offset on January 1, 1970 at 00:00 GMT.	 Since this is
       not necessarily the same	as the value at	some particular	time, the time
       in question should be converted to a tm structure using localtime() and
       the tm_gmtoff field of that structure should  be	 used.	 The  external
       variable	 daylight  is  non-zero	 if  and only if Daylight Savings Time
       would be	in effect within the current time zone at some time;  it  does
       not indicate whether Daylight Savings Time is currently in effect.

       The  external  variable tzname is an array of two char *	pointers.  The
       first pointer points to a character string that is the name of the cur-
       rent  time zone when Daylight Savings Time is not in effect; the	second
       one, if Daylight	Savings	Time conversion	should be applied, points to a
       character  string  that	is the name of the current time	zone when Day-
       light Savings Time is in	effect.	 These strings are updated  by	local-
       time()  whenever	 a  time is converted.	If Daylight Savings Time is in
       effect at the time being	converted, the second pointer is set to	 point
       to  the name of the current time	zone at	that time, otherwise the first
       pointer is so set.

       timezone, daylight, and tzname are retained for compatibility with  ex-
       isting programs.

FILES
       /usr/share/lib/zoneinfo	     standard  time conversion information di-
				     rectory
       /usr/share/lib/zoneinfo/localtime
				     local time	zone file
SEE ALSO
       gettimeofday(2),	getenv(3V), time(3V), environ(5V), tzfile(5)
BUGS
       The return values point to static data, whose contents are  overwritten
       by each call.  The tm_zone field	of a returned tm structure points to a
       static array of characters, which will also be overwritten at the  next
       call (and by calls to tzset() or	tzsetwall()).

				5 October 1989			     CTIME(3V)

NAME | SYNOPSIS | SYSTEM V SYNOPSIS | DESCRIPTION | SYSTEM V DESCRIPTION | FILES | SEE ALSO | BUGS

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

home | help