lib/libc/stdtime/time2posix.3

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