Annotation of src/lib/libc/time/time2posix.3, Revision 1.22
1.22 ! abhinav 1: .\" $NetBSD: time2posix.3,v 1.21 2017/10/25 19:04:07 abhinav Exp $
1.19 christos 2: .Dd October 6, 2014
1.8 wiz 3: .Dt TIME2POSIX 3
4: .Os
5: .Sh NAME
6: .Nm time2posix ,
1.16 christos 7: .Nm time2posix_z ,
8: .Nm posix2time ,
1.21 abhinav 9: .Nm posix2time_z
1.8 wiz 10: .Nd convert seconds since the Epoch
1.9 kleink 11: .Sh LIBRARY
12: .Lb libc
1.8 wiz 13: .Sh SYNOPSIS
1.13 wiz 14: .In time.h
1.8 wiz 15: .Ft time_t
16: .Fn time2posix "time_t t"
17: .Ft time_t
1.16 christos 18: .Fn time2posix_z "const timezone_t tz" "time_t t"
19: .Ft time_t
1.8 wiz 20: .Fn posix2time "time_t t"
1.16 christos 21: .Ft time_t
22: .Fn posix2time_z "const timezone_t tz" "time_t t"
1.8 wiz 23: .Sh DESCRIPTION
24: .St -p1003.1
1.19 christos 25: requires the
26: .Ft time_t
27: value of
28: .Dv 536457599
29: to stand for
1.8 wiz 30: .Dl Wed Dec 31 23:59:59 UTC 1986 .
31: This effectively implies that POSIX
1.19 christos 32: .Ft time_t
33: values cannot include leap seconds and, therefore,
1.1 jtc 34: that the system time must be adjusted as each leap occurs.
1.8 wiz 35: .Pp
1.1 jtc 36: If the time package is configured with leap-second support
1.8 wiz 37: enabled, however, no such adjustment is needed and
38: .Va time_t
39: values continue to increase over leap events
1.21 abhinav 40: (as a true
1.18 christos 41: .Dq "seconds since..."
42: value).
1.1 jtc 43: This means that these values will differ from those required by POSIX
44: by the net number of leap seconds inserted since the Epoch.
1.8 wiz 45: .Pp
46: Typically this is not a problem as the type
47: .Va time_t
48: is intended to be (mostly)
1.22 ! abhinav 49: opaque \(em
1.8 wiz 50: .Va time_t
51: values should only be obtained-from and
1.1 jtc 52: passed-to functions such as
1.8 wiz 53: .Xr time 3 ,
54: .Xr localtime 3 ,
1.16 christos 55: .Xr localtime_r 3 ,
56: .Xr localtime_rz 3 ,
1.8 wiz 57: .Xr mktime 3 ,
1.16 christos 58: .Xr mktime_z 3 ,
1.1 jtc 59: and
1.8 wiz 60: .Xr difftime 3 .
61: However, POSIX gives an arithmetic expression for directly computing a
62: .Va time_t
63: value from a given date/time, and the same relationship is assumed by
1.12 wiz 64: some (usually older) applications.
65: Any programs creating/dissecting
1.8 wiz 66: .Va time_t Ns 's
67: using such a relationship will typically not handle intervals over
68: leap seconds correctly.
69: .Pp
1.1 jtc 70: The
1.16 christos 71: .Fn time2posix ,
72: .Fn time2posix_z ,
1.17 wiz 73: .Fn posix2time ,
1.1 jtc 74: and
1.16 christos 75: .Fn posix2time_z
1.8 wiz 76: functions are provided to address this
77: .Va time_t
78: mismatch by converting between local
79: .Va time_t
1.12 wiz 80: values and their POSIX equivalents.
81: This is done by accounting for the number of time-base changes that would
82: have taken place on a POSIX system as leap seconds were inserted or deleted.
83: These converted values can then be used in lieu of correcting the
84: older applications, or when communicating with POSIX-compliant systems.
1.8 wiz 85: .Pp
86: .Fn time2posix
1.16 christos 87: and
88: .Fn time2posix_z
89: are single-valued.
1.12 wiz 90: That is, every local
1.8 wiz 91: .Va time_t
92: corresponds to a single POSIX
93: .Va time_t .
94: .Fn posix2time
1.16 christos 95: and
96: .Fn posix2time
97: are less well-behaved: for a positive leap second hit the result is not
1.8 wiz 98: unique, and for a negative leap second hit the corresponding POSIX
99: .Va time_t
1.12 wiz 100: doesn't exist so an adjacent value is returned.
101: Both of these are good indicators of the inferiority of the POSIX
102: representation.
1.8 wiz 103: .Pp
1.16 christos 104: The
105: .Dq z
106: variants of the two functions behave exactly like their counterparts,
107: but they operate in the given
108: .Fa tz
109: argument which was previously allocated using
110: .Xr tzalloc 3
111: and are re-entrant.
112: .Pp
1.8 wiz 113: The following table summarizes the relationship between a
114: .Va time_t
115: and its conversion to, and back from, the POSIX representation over
116: the leap second inserted at the end of June, 1993.
1.14 joerg 117: .Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
1.8 wiz 118: .It Sy DATE TIME T X=time2posix(T) posix2time(X)
119: .It 93/06/30 23:59:59 A+0 B+0 A+0
120: .It 93/06/30 23:59:60 A+1 B+1 A+1 or A+2
121: .It 93/07/01 00:00:00 A+2 B+1 A+1 or A+2
122: .It 93/07/01 00:00:01 A+3 B+2 A+3
123: .El
124: .Pp
1.1 jtc 125: A leap second deletion would look like...
1.14 joerg 126: .Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
1.8 wiz 127: .It Sy DATE TIME T X=time2posix(T) posix2time(X)
128: .It ??/06/30 23:59:58 A+0 B+0 A+0
129: .It ??/07/01 00:00:00 A+1 B+2 A+1
130: .It ??/07/01 00:00:01 A+2 B+3 A+2
131: .El
1.20 wiz 132: [Note: posix2time(B+1) => A+0 or A+1]
1.8 wiz 133: .Pp
134: If leap-second support is not enabled, local
135: .Va time_t Ns 's
136: and POSIX
137: .Va time_t Ns 's
138: are equivalent, and both
139: .Fn time2posix
1.1 jtc 140: and
1.8 wiz 141: .Fn posix2time
1.1 jtc 142: degenerate to the identity function.
1.8 wiz 143: .Sh SEE ALSO
144: .Xr difftime 3 ,
145: .Xr localtime 3 ,
1.16 christos 146: .Xr localtime_r 3 ,
147: .Xr localtime_rz 3 ,
1.8 wiz 148: .Xr mktime 3 ,
1.16 christos 149: .Xr mktime_z 3 ,
1.17 wiz 150: .Xr time 3 ,
151: .Xr tzalloc 3
1.7 jtc 152: .\" @(#)time2posix.3 7.7
1.5 jtc 153: .\" This file is in the public domain, so clarified as of
1.15 mlelstv 154: .\" 1996-06-05 by Arthur David Olson.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to time2posix.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / time