Annotation of src/lib/libc/time/time2posix.3, Revision 1.5
1.5 ! jtc 1: .\" $NetBSD: time2posix.3,v 1.4 1995/11/28 06:42:00 jtc Exp $
1.1 jtc 2: .TH TIME2POSIX 3
3: .SH NAME
4: time2posix, posix2time \- convert seconds since the Epoch
5: .SH SYNOPSIS
6: .nf
7: .B #include <sys/types.h>
8: .B #include <time.h>
9: .PP
10: .B time_t time2posix(t)
11: .B time_t t
12: .PP
13: .B time_t posix2time(t)
14: .B time_t t
15: .PP
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 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
1.4 jtc 41: .IR time(3) ,
1.1 jtc 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),
1.4 jtc 118: time(3)
1.5 ! jtc 119: .\" @(#)time2posix.3 7.4
! 120: .\" This file is in the public domain, so clarified as of
! 121: .\" June 5, 1996 by Arthur David Olson (arthur_david_olson@nih.gov).
CVSweb <webmaster@jp.NetBSD.org>