| blob | 775ebc79d7f934fd052e54dd688b92f9ddedb5f6 |
1 .\" $NetBSD: time2posix.3,v 1.14 2009/04/11 16:29:09 joerg Exp $
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
9 .Sh LIBRARY
10 .Lb libc
11 .Sh SYNOPSIS
12 .In time.h
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,
26 that the system time must be adjusted as each leap occurs.
27 .Pp
28 If the time package is configured with leap-second support
29 enabled, however, no such adjustment is needed and
30 .Va time_t
31 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
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
42 passed-to functions such as
43 .Xr time 3 ,
44 .Xr localtime 3 ,
45 .Xr mktime 3 ,
46 and
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
51 some (usually older) applications.
52 Any programs creating/dissecting
53 .Va time_t Ns 's
54 using such a relationship will typically not handle intervals over
55 leap seconds correctly.
56 .Pp
57 The
58 .Fn time2posix
59 and
60 .Fn posix2time
61 functions are provided to address this
62 .Va time_t
63 mismatch by converting between local
64 .Va time_t
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.
70 .Pp
71 .Fn time2posix
72 is single-valued.
73 That is, every local
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
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.
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.
89 .Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
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
97 A leap second deletion would look like...
98 .Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
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
104 [Note: posix2time(B+1) =\*[Gt] A+0 or A+1]
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
112 and
113 .Fn posix2time
114 degenerate to the identity function.
115 .Sh SEE ALSO
116 .Xr difftime 3 ,
117 .Xr localtime 3 ,
118 .Xr mktime 3 ,
119 .Xr time 3
120 .\" @(#)time2posix.3 7.7
121 .\" This file is in the public domain, so clarified as of
122 .\" 1996-06-05 by Arthur David Olson.