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