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