Return to time2posix.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/time2posix.3, Revision 1.14

1.14    ! joerg       1: .\"    $NetBSD: time2posix.3,v 1.13 2003/04/16 13:34:58 wiz Exp $
1.8       wiz         2: .Dd April 1, 2001
                      3: .Dt TIME2POSIX 3
                      4: .Os
                      5: .Sh NAME
                      6: .Nm time2posix ,
                      7: .Nm posix2time
                      8: .Nd convert seconds since the Epoch
1.9       kleink      9: .Sh LIBRARY
                     10: .Lb libc
1.8       wiz        11: .Sh SYNOPSIS
1.13      wiz        12: .In time.h
1.8       wiz        13: .Ft time_t
                     14: .Fn time2posix "time_t t"
                     15: .Ft time_t
                     16: .Fn posix2time "time_t t"
                     17: .Sh DESCRIPTION
                     18: .St -p1003.1
                     19: legislates that a
                     20: .Va time_t
                     21: value of 536457599 shall correspond to
                     22: .Dl Wed Dec 31 23:59:59 UTC 1986 .
                     23: This effectively implies that POSIX
                     24: .Va time_t Ns 's
                     25: cannot include leap seconds and, therefore,
1.1       jtc        26: that the system time must be adjusted as each leap occurs.
1.8       wiz        27: .Pp
1.1       jtc        28: If the time package is configured with leap-second support
1.8       wiz        29: enabled, however, no such adjustment is needed and
                     30: .Va time_t
                     31: values continue to increase over leap events
1.1       jtc        32: (as a true `seconds since...' value).
                     33: This means that these values will differ from those required by POSIX
                     34: by the net number of leap seconds inserted since the Epoch.
1.8       wiz        35: .Pp
                     36: Typically this is not a problem as the type
                     37: .Va time_t
                     38: is intended to be (mostly)
                     39: opaque \(em
                     40: .Va time_t
                     41: values should only be obtained-from and
1.1       jtc        42: passed-to functions such as
1.8       wiz        43: .Xr time 3 ,
                     44: .Xr localtime 3 ,
                     45: .Xr mktime 3 ,
1.1       jtc        46: and
1.8       wiz        47: .Xr difftime 3 .
                     48: However, POSIX gives an arithmetic expression for directly computing a
                     49: .Va time_t
                     50: value from a given date/time, and the same relationship is assumed by
1.12      wiz        51: some (usually older) applications.
                     52: Any programs creating/dissecting
1.8       wiz        53: .Va time_t Ns 's
                     54: using such a relationship will typically not handle intervals over
                     55: leap seconds correctly.
                     56: .Pp
1.1       jtc        57: The
1.8       wiz        58: .Fn time2posix
1.1       jtc        59: and
1.8       wiz        60: .Fn posix2time
                     61: functions are provided to address this
                     62: .Va time_t
                     63: mismatch by converting between local
                     64: .Va time_t
1.12      wiz        65: values and their POSIX equivalents.
                     66: This is done by accounting for the number of time-base changes that would
                     67: have taken place on a POSIX system as leap seconds were inserted or deleted.
                     68: These converted values can then be used in lieu of correcting the
                     69: older applications, or when communicating with POSIX-compliant systems.
1.8       wiz        70: .Pp
                     71: .Fn time2posix
1.12      wiz        72: is single-valued.
                     73: That is, every local
1.8       wiz        74: .Va time_t
                     75: corresponds to a single POSIX
                     76: .Va time_t .
                     77: .Fn posix2time
                     78: is less well-behaved: for a positive leap second hit the result is not
                     79: unique, and for a negative leap second hit the corresponding POSIX
                     80: .Va time_t
1.12      wiz        81: doesn't exist so an adjacent value is returned.
                     82: Both of these are good indicators of the inferiority of the POSIX
                     83: representation.
1.8       wiz        84: .Pp
                     85: The following table summarizes the relationship between a
                     86: .Va time_t
                     87: and its conversion to, and back from, the POSIX representation over
                     88: the leap second inserted at the end of June, 1993.
1.14    ! joerg      89: .Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
1.8       wiz        90: .It Sy DATE    TIME    T       X=time2posix(T) posix2time(X)
                     91: .It 93/06/30   23:59:59        A+0     B+0     A+0
                     92: .It 93/06/30   23:59:60        A+1     B+1     A+1 or A+2
                     93: .It 93/07/01   00:00:00        A+2     B+1     A+1 or A+2
                     94: .It 93/07/01   00:00:01        A+3     B+2     A+3
                     95: .El
                     96: .Pp
1.1       jtc        97: A leap second deletion would look like...
1.14    ! joerg      98: .Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
1.8       wiz        99: .It Sy DATE    TIME    T       X=time2posix(T) posix2time(X)
                    100: .It ??/06/30   23:59:58        A+0     B+0     A+0
                    101: .It ??/07/01   00:00:00        A+1     B+2     A+1
                    102: .It ??/07/01   00:00:01        A+2     B+3     A+2
                    103: .El
1.11      ross      104: [Note: posix2time(B+1) =\*[Gt] A+0 or A+1]
1.8       wiz       105: .Pp
                    106: If leap-second support is not enabled, local
                    107: .Va time_t Ns 's
                    108: and POSIX
                    109: .Va time_t Ns 's
                    110: are equivalent, and both
                    111: .Fn time2posix
1.1       jtc       112: and
1.8       wiz       113: .Fn posix2time
1.1       jtc       114: degenerate to the identity function.
1.8       wiz       115: .Sh SEE ALSO
                    116: .Xr difftime 3 ,
                    117: .Xr localtime 3 ,
                    118: .Xr mktime 3 ,
                    119: .Xr time 3
1.7       jtc       120: .\" @(#)time2posix.3   7.7
1.5       jtc       121: .\" This file is in the public domain, so clarified as of
1.6       jtc       122: .\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).