man/man3/time2posix.3

   1 .TH TIME2POSIX 3
   2 .SH NAME
   3 time2posix, posix2time \- convert seconds since the Epoch
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <sys/types.h>
   7 .B #include <time.h>
   8 .PP
   9 .B time_t time2posix(t)
  10 .B time_t t
  11 .PP
  12 .B time_t posix2time(t)
  13 .B time_t t
  14 .PP
  15 .B cc ... -ltz
  16 .fi
  17 .SH DESCRIPTION
  18 IEEE Standard 1003.1
  19 (POSIX)
  20 legislates that a time_t value of
  21 536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 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 .IR time(2) ,
  42 .IR localtime(3) ,
  43 .IR mktime(3) ,
  44 and
  45 .IR difftime(3) .
  46 However,
  47 POSIX gives an arithmetic
  48 expression for directly computing a time_t value from a given date/time,
  49 and the same relationship is assumed by some
  50 (usually older)
  51 applications.
  52 Any programs creating/dissecting time_t's
  53 using such a relationship will typically not handle intervals
  54 over leap seconds correctly.
  55 .PP
  56 The
  57 .I time2posix
  58 and
  59 .I posix2time
  60 functions are provided to address this time_t mismatch by converting
  61 between local time_t values and their POSIX equivalents.
  62 This is done by accounting for the number of time-base changes that
  63 would have taken place on a POSIX system as leap seconds were inserted
  64 or deleted.
  65 These converted values can then be used in lieu of correcting the older
  66 applications,
  67 or when communicating with POSIX-compliant systems.
  68 .PP
  69 .I Time2posix
  70 is single-valued.
  71 That is,
  72 every local time_t
  73 corresponds to a single POSIX time_t.
  74 .I Posix2time
  75 is less well-behaved:
  76 for a positive leap second hit the result is not unique,
  77 and for a negative leap second hit the corresponding
  78 POSIX time_t doesn't exist so an adjacent value is returned.
  79 Both of these are good indicators of the inferiority of the
  80 POSIX representation.
  81 .PP
  82 The following table summarizes the relationship between a time
  83 T and it's conversion to,
  84 and back from,
  85 the POSIX representation over the leap second inserted at the end of June,
  86 1993.
  87 .nf
  88 .ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u
  89 DATE    TIME    T       X=time2posix(T) posix2time(X)
  90 93/06/30        23:59:59        A+0     B+0     A+0
  91 93/06/30        23:59:60        A+1     B+1     A+1 or A+2
  92 93/07/01        00:00:00        A+2     B+1     A+1 or A+2
  93 93/07/01        00:00:01        A+3     B+2     A+3
  94
  95 A leap second deletion would look like...
  96
  97 DATE    TIME    T       X=time2posix(T) posix2time(X)
  98 ??/06/30        23:59:58        A+0     B+0     A+0
  99 ??/07/01        00:00:00        A+1     B+2     A+1
 100 ??/07/01        00:00:01        A+2     B+3     A+2
 101 .sp
 102 .ce
 103         [Note: posix2time(B+1) => A+0 or A+1]
 104 .fi
 105 .PP
 106 If leap-second support is not enabled,
 107 local time_t's and
 108 POSIX time_t's are equivalent,
 109 and both
 110 .I time2posix
 111 and
 112 .I posix2time
 113 degenerate to the identity function.
 114 .SH SEE ALSO
 115 difftime(3),
 116 localtime(3),
 117 mktime(3),
 118 time(2)
 119 .\" @(#)time2posix.3    7.8
 120 .\" This file is in the public domain, so clarified as of
 121 .\" 1996-06-05 by Arthur David Olson.