time2posix

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 ... -lz

DESCRIPTION

       IEEE  Standard  1003.1  (POSIX)  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, 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 rela-
       tionship 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 corre-
       sponding 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)