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