time2posix.3.txt

NAME

     time2posix, posix2time - convert seconds since the Epoch

SYNOPSIS
     #include <sys/types.h>
     #include <time.h>

     time_t time2posix(t)
     time_t t

     time_t posix2time(t)
     time_t t

     cc ... -ltz

DESCRIPTION
     IEEE Standard 1003.1 (POSIX) legislates that a time_t value
     of 536457599 shall correspond to "Wed Dec 31 23:59:59 UTC
     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, however, 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(2),
     localtime(3), mktime(3), and difftime(3).  However, POSIX
     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 typically 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.

     Time2posix is single-valued.  That is, every local time_t
     corresponds to a single POSIX time_t.  Posix2time 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 doesn't exist so an adjacent
     value is returned.  Both of these are good indicators of the
     inferiority of the POSIX representation.

     The following table summarizes the relationship between a
     time T and it's conversion to, and back from, the POSIX
     representation over the leap second 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(2)