lib/libc/time/time2posix.3

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