1.TH TIME2POSIX 3
2.SH NAME
3time2posix, posix2time \- convert seconds since the Epoch
4.SH SYNOPSIS
5.nf
6.B #include <time.h>
7.PP
8.B time_t time2posix(t)
9.B time_t t
10.PP
11.B time_t posix2time(t)
12.B time_t t
13.PP
14.B cc ... -lz
15.fi
16.SH DESCRIPTION
17IEEE Standard 1003.1
18(POSIX)
| 1.Dd May 1, 1996
2.Dt TIME2POSIX 3
3.Os
4.Sh NAME
5.Nm time2posix ,
6.Nm posix2time
7.Nd convert seconds since the Epoch
8.Sh SYNOPSIS
9.Fd #include <time.h>
10.Ft time_t
11.Fn time2posix "const time_t *t"
12.Ft time_t
13.Fn posix2time "const time_t *t"
14.Sh DESCRIPTION
15.St -p1003.1-88
|
19legislates that a time_t value of
20536457599 shall correspond to "Wed Dec 31 23:59:59 GMT 1986."
21This effectively implies that POSIX time_t's cannot include leap
22seconds and,
23therefore,
24that the system time must be adjusted as each leap occurs.
| 16legislates that a time_t value of
17536457599 shall correspond to "Wed Dec 31 23:59:59 GMT 1986."
18This effectively implies that POSIX time_t's cannot include leap
19seconds and,
20therefore,
21that the system time must be adjusted as each leap occurs.
|
25.PP
| 22.Pp
|
26If the time package is configured with leap-second support
27enabled,
28however,
29no such adjustment is needed and
30time_t values continue to increase over leap events
31(as a true `seconds since...' value).
32This means that these values will differ from those required by POSIX
33by the net number of leap seconds inserted since the Epoch.
| 23If the time package is configured with leap-second support
24enabled,
25however,
26no such adjustment is needed and
27time_t values continue to increase over leap events
28(as a true `seconds since...' value).
29This means that these values will differ from those required by POSIX
30by the net number of leap seconds inserted since the Epoch.
|
34.PP
| 31.Pp
|
35Typically this is not a problem as the type time_t is intended
36to be
37(mostly)
38opaque\(emtime_t values should only be obtained-from and
39passed-to functions such as
| 32Typically this is not a problem as the type time_t is intended
33to be
34(mostly)
35opaque\(emtime_t values should only be obtained-from and
36passed-to functions such as
|
40.IR time(2) ,
41.IR localtime(3) ,
42.IR mktime(3) ,
| 37.Xr time 2 ,
38.Xr localtime 3 ,
39.Xr mktime 3
|
43and
| 40and
|
44.IR difftime(3) .
| 41.Xr difftime 3 .
|
45However,
| 42However,
|
46POSIX gives an arithmetic
| 43.Std -p1003.1-88
44gives an arithmetic
|
47expression for directly computing a time_t value from a given date/time,
48and the same relationship is assumed by some
49(usually older)
50applications.
51Any programs creating/dissecting time_t's
52using such a relationship will typically not handle intervals
53over leap seconds correctly.
| 45expression for directly computing a time_t value from a given date/time,
46and the same relationship is assumed by some
47(usually older)
48applications.
49Any programs creating/dissecting time_t's
50using such a relationship will typically not handle intervals
51over leap seconds correctly.
|
54.PP
| 52.Pp
|
55The
| 53The
|
56.I time2posix
| 54.Fn time2posix
|
57and
| 55and
|
58.I posix2time
| 56.Fn posix2time
|
59functions are provided to address this time_t mismatch by converting
60between local time_t values and their POSIX equivalents.
61This is done by accounting for the number of time-base changes that
62would have taken place on a POSIX system as leap seconds were inserted
63or deleted.
64These converted values can then be used in lieu of correcting the older
65applications,
66or when communicating with POSIX-compliant systems.
| 57functions are provided to address this time_t mismatch by converting
58between local time_t values and their POSIX equivalents.
59This is done by accounting for the number of time-base changes that
60would have taken place on a POSIX system as leap seconds were inserted
61or deleted.
62These converted values can then be used in lieu of correcting the older
63applications,
64or when communicating with POSIX-compliant systems.
|
67.PP
68.I Time2posix
69is single-valued.
| 65.Pp
66The
67.Fn time2posix
68function is single-valued.
|
70That is,
71every local time_t
72corresponds to a single POSIX time_t.
| 69That is,
70every local time_t
71corresponds to a single POSIX time_t.
|
73.I Posix2time
74is less well-behaved:
| 72The
73.Fn posix2time
74function is less well-behaved:
|
75for a positive leap second hit the result is not unique,
76and for a negative leap second hit the corresponding
77POSIX time_t doesn't exist so an adjacent value is returned.
78Both of these are good indicators of the inferiority of the
79POSIX representation.
| 75for a positive leap second hit the result is not unique,
76and for a negative leap second hit the corresponding
77POSIX time_t doesn't exist so an adjacent value is returned.
78Both of these are good indicators of the inferiority of the
79POSIX representation.
|
80.PP
81The following table summarizes the relationship between a time
82T and it's conversion to,
| 80.Pp
81The following table summarizes the relationship between a time_t
82nd it's conversion to,
|
83and back from,
84the POSIX representation over the leap second inserted at the end of June,
851993.
| 83and back from,
84the POSIX representation over the leap second inserted at the end of June,
851993.
|
86.nf
| |
87.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u
88DATE TIME T X=time2posix(T) posix2time(X)
8993/06/30 23:59:59 A+0 B+0 A+0
9093/06/30 23:59:60 A+1 B+1 A+1 or A+2
9193/07/01 00:00:00 A+2 B+1 A+1 or A+2
9293/07/01 00:00:01 A+3 B+2 A+3
93
94A leap second deletion would look like...
95
96DATE TIME T X=time2posix(T) posix2time(X)
97??/06/30 23:59:58 A+0 B+0 A+0
98??/07/01 00:00:00 A+1 B+2 A+1
99??/07/01 00:00:01 A+2 B+3 A+2
| 86.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u
87DATE TIME T X=time2posix(T) posix2time(X)
8893/06/30 23:59:59 A+0 B+0 A+0
8993/06/30 23:59:60 A+1 B+1 A+1 or A+2
9093/07/01 00:00:00 A+2 B+1 A+1 or A+2
9193/07/01 00:00:01 A+3 B+2 A+3
92
93A leap second deletion would look like...
94
95DATE TIME T X=time2posix(T) posix2time(X)
96??/06/30 23:59:58 A+0 B+0 A+0
97??/07/01 00:00:00 A+1 B+2 A+1
98??/07/01 00:00:01 A+2 B+3 A+2
|
100.sp
101.ce
| 99.Pp
|
102 [Note: posix2time(B+1) => A+0 or A+1]
| 100 [Note: posix2time(B+1) => A+0 or A+1]
|
103.fi
104.PP
| 101.Pp
|
105If leap-second support is not enabled,
106local time_t's and
107POSIX time_t's are equivalent,
108and both
| 102If leap-second support is not enabled,
103local time_t's and
104POSIX time_t's are equivalent,
105and both
|
109.I time2posix
| 106.Fn time2posix
|
110and
| 107and
|
111.I posix2time
| 108.Fn posix2time
|
112degenerate to the identity function.
| 109degenerate to the identity function.
|
113.SH SEE ALSO
114difftime(3),
115localtime(3),
116mktime(3),
117time(3)
118.\" @(#)time2posix.3 7.3
| 110.Sh "SEE ALSO"
111.Xr difftime 3 ,
112.Xr localtime 3 ,
113.Xr mktime 3 ,
114.Xr time 3
|
| |