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