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