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

FreeBSD Manual Pages

  
 
  

home | help
CTIME(3)	       FreeBSD Library Functions Manual		      CTIME(3)

NAME
     asctime, asctime_r, ctime,	ctime_r, ctime_rz, difftime, gmtime, gmtime_r,
     localtime,	localtime_r, localtime_rz, mktime, mktime_z -- convert date
     and time

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <time.h>

     extern char *tzname[2];

     char *
     asctime(const struct tm *tm);

     char *
     asctime_r(const struct tm *restrict tm, char * restrict buf);

     char *
     ctime(const time_t	*clock);

     char *
     ctime_r(const time_t *clock, char *buf);

     char *
     ctime_rz(timezone_t restrict tz, const time_t *clock, char	*buf);

     double
     difftime(time_t time1, time_t time0);

     struct tm *
     gmtime(const time_t *clock);

     struct tm *
     gmtime_r(const time_t * restrict clock, struct tm * restrict result);

     struct tm *
     localtime(const time_t *clock);

     struct tm *
     localtime_r(const time_t *	restrict clock,	struct tm * restrict result);

     struct tm *
     localtime_rz(timezone_t restrict tz, const	time_t * restrict clock,
	 struct	tm * restrict result);

     time_t
     mktime(struct tm *tm);

     time_t
     mktime_z(timezone_t restrict tz, struct tm	*restrict tm);

DESCRIPTION
     The asctime family	of functions provide various standard library routines
     to	operate	with time and conversions related to time.

FUNCTIONS
     asctime(tm)
	   The asctime() function converts a time value	contained in the tm
	   structure to	a string with the following general format:

		 Thu Nov 24 18:22:48 1986\n\0

	   The tm structure is described in tm(3).

     asctime_r(tm, buf)
	   The asctime_r() has the same	behavior as asctime(), but the result
	   is stored in	buf, which should have a size of at least 26 bytes.

     ctime(clock)
	   The ctime() function	converts a time_t, pointed to by clock,	and
	   returns a pointer to	a string with the format described above.
	   Years requiring fewer than four characters are padded with leading
	   zeroes.  For	years longer than four characters, the string is of
	   the form

		 Thu Nov 24 18:22:48	 81986\n\0

	   with	five spaces before the year.  These unusual formats are	de-
	   signed to make it less likely that older software that expects ex-
	   actly 26 bytes of output will mistakenly output misleading values
	   for out-of-range years.

	   The clock time stamp	represents the time in seconds since
	   1970-01-01 00:00:00 Coordinated Universal Time (UTC).  The POSIX
	   standard says that time stamps must be nonnegative and must ignore
	   leap	seconds.  Many implementations extend POSIX by allowing	nega-
	   tive	time stamps, and can therefore represent time stamps that pre-
	   date	the introduction of UTC	and are	some other flavor of Universal
	   Time	(UT).  Some implementations support leap seconds, in contra-
	   diction to POSIX.

     ctime_r(clock, buf)
	   The ctime_r() is similar to ctime(),	except it places the result of
	   the conversion in the buf argument, which should be 26 or more
	   bytes long, instead of using	a global static	buffer.

     ctime_rz(tz, clock, buf)
	   The ctime_rz() function is similar to ctime_r(), but	it also	takes
	   a timezone_t	argument, as returned by a previous call to tzalloc(),
	   or a	NULL pointer denoting Coordinated Universal Time (UTC).

     difftime(time1, time2)
	   The difftime() function returns the difference between two calendar
	   times, (time1 - time0), expressed in	seconds.

	   The ctime_r(), localtime_r(), gmtime_r(), and asctime_r() functions
	   are like their unsuffixed counterparts, except that they accept an
	   additional argument specifying where	to store the result if suc-
	   cessful.

	   The ctime_rz(), localtime_rz(), and mktime_z() functions are	like
	   their unsuffixed counterparts, except that they accept an extra
	   initial zone	argument specifying the	timezone to be used for	con-
	   version.  If	zone is	NULL, UT is used; otherwise, zone should have
	   been	allocated by tzalloc() and should not be freed until after all
	   uses	(e.g., by calls	to strftime()) of the filled-in	tm_zone()
	   fields.

     gmtime(clock)
	   The gmtime()	function converts to Coordinated Universal Time	(UTC)
	   and returns a pointer to the	tm structure described in tm(3).

     gmtime_r(clock, result)
	   The gmtime_r() function provides the	same functionality as
	   gmtime(), differing in that the caller must supply a	buffer area
	   result in which the result is stored.

     localtime(clock)
	   Also	localtime() is comparable to gmtime().	However, localtime()
	   corrects for	the timezone and any timezone adjustments (such	as
	   Daylight Saving Time	in the U.S.A.).	 After filling in the tm
	   structure, the function sets	the tm_isdst'th	element	of tzname to a
	   pointer to an ASCII string that is the timezone abbreviation	to be
	   used	with localtime()'s return value.

     localtime_r(clock,	result)
	   As gmtime_r(), the localtime_r() takes an additional	buffer result
	   as a	parameter and stores the result	in it.	Note however that
	   localtime_r() does not imply	initialization of the local time con-
	   version information;	the application	may need to do so by calling
	   tzset(3).

     localtime_rz(tz, clock, result)
	   The localtime_rz() function is similar to localtime_r(), but	it
	   also	takes a	timezone_t argument, returned by a previous call to
	   tzalloc(), or a NULL	pointer	denoting Coordinated Universal Time
	   (UTC).

     mktime(tm)
	   The mktime()	function converts the broken-down time,	expressed as
	   local time in the tm(3) structure, into a calendar time value with
	   the same encoding as	that of	the values returned by the time(3)
	   function.  The following remarks should be taken into account.

	   +o   The original values of the tm_wday and tm_yday components of
	       the structure are ignored, and the original values of the other
	       components are not restricted to	their normal ranges.  (A posi-
	       tive or zero value for tm_isdst causes mktime() to presume ini-
	       tially that daylight saving time	respectively, is or is not in
	       effect for the specified	time.

	   +o   A negative value	for tm_isdst causes the	mktime() function to
	       attempt to divine whether daylight saving time is in effect for
	       the specified time; in this case	it does	not use	a consistent
	       rule and	may give a different answer when later presented with
	       the same	argument.

	   +o   On successful completion, the values of the tm_wday and tm_yday
	       components of the structure are set appropriately, and the
	       other components	are set	to represent the specified calendar
	       time, but with their values forced to their normal ranges; the
	       final value of tm_mday is not set until tm_mon and tm_year are
	       determined.

	   The function	returns	the specified calendar time; if	the calendar
	   time	cannot be represented, it returns (time_t)-1.  This can	happen
	   either because the resulting	conversion would not fit in a time_t
	   variable, or	because	the time specified happens to be in the	day-
	   light savings gap and tm_isdst was set to -1.  Other	mktime() im-
	   plementations do not	return an error	in the second case and return
	   the appropriate time	offset after the daylight savings gap.	There
	   is code to mimick this behavior, but	it is not enabled by default.

     mktime_z(tz, tm)
	   The mktime_z() function is similar to mktime() but it also takes a
	   const timezone_t argument, returned by a previous call to
	   tzalloc(), or a null	pointer	denoting Coordinated Universal Time
	   (UTC).

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

	    int	tm_sec;	     /*	seconds	(0 - 60) */
	    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;    /*	is summer time in effect? */
	     int tm_isdst;   /*	is daylight saving time	in effect? */
	    char *tm_zone;   /*	abbreviation of	timezone name (optional) */
	    long tm_gmtoff;  /*	offset from UT in seconds (optional) */

     +o	 tm_isdst is non-zero if daylight saving time is in effect.

     +o	 tm_gmtoff is the offset (in seconds) of the time represented from UT,
	 with positive values indicating east of the Prime Meridian.  The
	 field's name is derived from Greenwich	Mean Time, a precursor of UT.
     In	struct tm the tm_zone and tm_gmtoff fields exist, and are filled in,
     only if arrangements to do	so were	made when the library containing these
     functions	was created.  Similarly, the tzname variable is	optional.
     There is no guarantee that	these fields and this variable will continue
     to	exist in this form in future releases of this code.

RETURN VALUES
     +o	 On success the	asctime() and ctime() functions	return a pointer to a
	 static	character buffer, and the asctime_r(), ctime_r(), and
	 ctime_rz() function return a pointer to the user-supplied buffer.  On
	 failure they all return NULL and no errors are	defined	for them.

     +o	 On success the	gmtime(), and localtime() functions return a pointer
	 to a statically allocated struct tm whereas the gmtime_r(),
	 localtime_r(),	and localtime_rz(), functions return a pointer to the
	 user-supplied struct tm.  On failure they all return NULL and the
	 global	variable errno is set to indicate the error.

     +o	 The mktime() and mktime_z() function returns the specified time since
	 the Epoch as a	time_t type value.  If the time	cannot be represented,
	 then mktime() and mktime_z() return (time_t)-1	setting	the global
	 variable errno	to indicate the	error.

     +o	 The tzalloc() function	returns	a pointer to a timezone_t object or
	 NULL on failure, setting errno	to indicate the	error.	It may also
	 return	NULL when the name argument is NULL, and this is not an	error,
	 but a way of referring	to Coordinated Universal Time (UTC).

     +o	 tzgetzone() function returns string containing	the name of the	time-
	 zone given in tz.

FILES
     /etc/localtime		     local timezone file
     /usr/share/zoneinfo	     timezone information directory
     usr/share/zoneinfo/localtime    local timezone file
     /usr/share/zoneinfo/posixrules  used with POSIX-style TZ's
     /usr/share/zoneinfo/GMT	     for UTC leap seconds

     If	/usr/share/zoneinfo/GMT	is absent, UTC leap seconds are	loaded from
     /usr/share/zoneinfo/posixrules.

ERRORS
     The described functions may fail with

     [EINVAL]		The result cannot be represented because a parameter
			is incorrect, or the conversion	failed because no such
			time exists (for example a time	in the DST gap).

     [EOVERFLOW]	The result cannot be represented because the time re-
			quested	is out of bounds and the time calculation re-
			sulted in overflow.

     All functions that	return values, except their "z"	variants, can also re-
     turn the same errors as open(2) and malloc(3).

SEE ALSO
     getenv(3),	strftime(3), time(3), tm(3), tzset(3), tzfile(5)

STANDARDS
     The ctime(), difftime(), asctime(), localtime(), gmtime() and mktime()
     functions conform to ANSI X3.159-1989 ("ANSI C89").  Rest of the func-
     tions conform to IEEE Std 1003.1-2008 ("POSIX.1").

HISTORY
     A ctime() function	appeared in Version 1 AT&T UNIX.

CAVEATS
     The functions that	do not take an explicit	timezone_t argument return
     values pointing to	static data; the data is overwritten by	each call.
     For the above functions the tzname	variable (once set) and	the tm_zone
     field of a	returned struct	tm point to an array of	characters that	can be
     freed or overwritten by later calls to the	functions localtime(),
     tzfree(), and tzset(), if these functions affect the timezone information
     that specifies the	abbreviation in	question.  The remaining functions and
     data are thread-safe.  The	functions that do take an explicit timezone_t
     argument and set the fields of a supplied struct tm should	not call
     tzfree() since the	tm_zone	field of the struct tm points to data allo-
     cated by tzalloc().

     The asctime(), asctime_r(), ctime(), ctime_r(), and ctime_rz(), functions
     behave strangely for years	before 1000 or after 9999.  The	1989 and 1999
     editions of the C Standard	say that years from -99	through	999 are	con-
     verted without extra spaces, but this conflicts with longstanding tradi-
     tion and with this	implementation.	 The 2011 edition says that the	behav-
     ior is undefined if the year is before 1000 or after 9999.	 Traditional
     implementations of	these two functions are	restricted to years in the
     range 1900	through	2099.  To avoid	this portability mess, new programs
     should use	strftime() instead.

FreeBSD	13.0		       September 2, 2019		  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | FUNCTIONS | RETURN VALUES | FILES | ERRORS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=localtime&sektion=3&manpath=NetBSD+9.2>

home | help