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

FreeBSD Manual Pages

  
 
  

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

NAME
     time2posix, posix2time -- convert seconds since the Epoch

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <time.h>

     time_t
     time2posix(time_t t);

     time_t
     posix2time(time_t t);

DESCRIPTION
     IEEE Std 1003.1-1988 (``POSIX.1'')	legislates that	a time_t value of
     536457599 shall correspond	to "Wed	Dec 31 23:59:59	GMT 1986."  This
     effectively implies that POSIX time_t's cannot include leap seconds and,
     therefore,	that the system	time must be adjusted as each leap occurs.

     If	the time package is configured with leap-second	support	enabled, how-
     ever, no such adjustment is needed	and time_t values continue to increase
     over leap events (as a true `seconds since...' value).  This means	that
     these values will differ from those required by POSIX by the net number
     of	leap seconds inserted since the	Epoch.

     Typically this is not a problem as	the type time_t	is intended to be
     (mostly) opaque--time_t values should only	be obtained-from and passed-to
     functions such as time(3),	localtime(3), mktime(3)	and difftime(3).  How-
     ever, IEEE	Std 1003.1-1988	(``POSIX.1'') gives an arithmetic expression
     for directly computing a time_t value from	a given	date/time, and the
     same relationship is assumed by some (usually older) applications.	 Any
     programs creating/dissecting time_t's using such a	relationship will typ-
     ically not	handle intervals over leap seconds correctly.

     The time2posix() and posix2time() functions are provided to address this
     time_t mismatch by	converting between local time_t	values and their POSIX
     equivalents.  This	is done	by accounting for the number of	time-base
     changes that would	have taken place on a POSIX system as leap seconds
     were inserted or deleted.	These converted	values can then	be used	in
     lieu of correcting	the older applications,	or when	communicating with
     POSIX-compliant systems.

     The time2posix() function is single-valued.  That is, every local time_t
     corresponds to a single POSIX time_t.  The	posix2time() function is less
     well-behaved: for a positive leap second hit the result is	not unique,
     and for a negative	leap second hit	the corresponding POSIX	time_t does
     not exist so an adjacent value is returned.  Both of these	are good indi-
     cators of the inferiority of the POSIX representation.

     The following table summarizes the	relationship between time_t and	its
     conversion	to, and	back from, the POSIX representation over the leap sec-
     ond inserted at the end of	June, 1993.

     DATE	 TIME	     T	    X=time2posix(T)    posix2time(X)
     93/06/30	 23:59:59    A+0    B+0		       A+0
     93/06/30	 23:59:60    A+1    B+1		       A+1 or A+2
     93/07/01	 00:00:00    A+2    B+1		       A+1 or A+2
     93/07/01	 00:00:01    A+3    B+2		       A+3

     A leap second deletion would look like...

     DATE	 TIME	     T	    X=time2posix(T)    posix2time(X)
     ??/06/30	 23:59:58    A+0    B+0		       A+0
     ??/07/01	 00:00:00    A+1    B+2		       A+1
     ??/07/01	 00:00:01    A+2    B+3		       A+2

	   [Note: posix2time(B+1) => A+0 or A+1]

     If	leap-second support is not enabled, local time_t's and POSIX time_t's
     are equivalent, and both time2posix() and posix2time() degenerate to the
     identity function.

SEE ALSO
     difftime(3), localtime(3),	mktime(3), time(3)

FreeBSD	Ports 11.2	      September	11, 2005	    FreeBSD Ports 11.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=posix2time&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help