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