lib/libc/time/time2posix.3

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