1.\" This file is in the public domain, so clarified as of 2.\" 1996-06-05 by Arthur David Olson. 3.Dd March 8, 2026 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 20says that 21.B time_t 22values cannot count leap 23seconds and, 24therefore, 25that the system time must be adjusted as each leap occurs. 26.Pp 27If the time package is configured with leap-second support 28enabled, 29however, 30no such adjustment is needed and 31.Vt time_t 32values continue to increase over leap events 33(as a true 34.Dq "seconds since..." 35value). 36This means that these values will differ from those required by POSIX 37by the net number of leap seconds inserted since the Epoch. 38.Pp 39For many C programs this is not a problem as the C standard says that 40.Vt time_t 41is 42(mostly) 43opaque \(em 44.Vt time_t 45values should be obtained from and 46passed to functions such as 47.Xr time 2 , 48.Xr localtime 3 , 49.Xr mktime 3 , 50and 51.Xr difftime 3 . 52However, 53POSIX gives an arithmetic 54expression for computing a 55.Vt time_t 56value directly from a given Universal date and time, 57and the same relationship is assumed by some 58applications. 59Any programs creating/dissecting 60.Vt time_t 61values 62using such a relationship will typically not handle intervals 63over leap seconds correctly. 64.Pp 65The 66.Fn time2posix 67and 68.Fn posix2time 69functions address this mismatch by converting 70between local 71.Vt time_t 72values and their POSIX equivalents. 73This is done by accounting for the number of time-base changes that 74would have taken place on a POSIX system as leap seconds were inserted 75or deleted. 76These converted values can then be used 77when communicating with POSIX-compliant systems. 78.Pp 79The 80.Fn time2posix 81function converts a 82.Vt time_t 83value to its POSIX counterpart, if one exists. 84The 85.Fn posix2time 86function does the reverse but 87is less well-behaved: 88for a positive leap second hit the result is not unique, 89and for a negative leap second hit the corresponding 90POSIX 91.Vt time_t 92doesn't exist so an adjacent value is returned. 93Both of these are indicate problems with the 94POSIX representation. 95.Pp 96The following table summarizes the relationship between a time 97T and its conversion to, 98and back from, 99the POSIX representation over the leap second inserted at the end of June, 1001993. 101In this table, 102.Li X=time2posix(T) , 103.Li Y=posix2time(X) , 104.Li A=741484816 , 105and 106.Li B=A\-17 107because 17 positive leap seconds preceded this leap second. 108.Pp 109.Bl -column "1993-06-30" "23:59:59" "A+0" "B+0" 110.It DATE TIME T X Y 111.It 1993-06-30 23:59:59 A B A 112.It 1993-06-30 23:59:60 A+1 B+1 A+1 or A+2 113.It 1993-07-01 00:00:00 A+2 B+1 A+1 or A+2 114.It 1993-07-01 00:00:01 A+3 B+2 A+3 115.El 116.Pp 117A leap second deletion would look like the following, and 118.Li posix2time(B+1) 119would return either 120.Li A 121or 122.Li A+1 . 123.Pp 124.Bl -column "????-06-30" "23:59:58" "A+1" "B+2" "A+1" 125.It DATE TIME T X Y 126.It ????-06-30 23:59:58 A B A 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 131If leap-second support is not enabled, 132local 133.Vt time_t 134and 135POSIX 136.Vt time_t 137values are equivalent, 138and both 139.Fn time2posix 140and 141.Fn posix2time 142degenerate to the identity function. 143.Sh RETURN VALUES 144If successful, these functions return the resulting timestamp without modifying 145.Va errno . 146Otherwise, they set 147.Va errno 148and return 149.Li "((time_t) -1)" . 150.Sh ERRORS 151These functions fail if: 152.Bl -tag -width Er 153.It Bq Er EOVERFLOW 154The resulting value cannot be represented. 155This can happen for 156.Fn posix2time 157if its argument is close to the maximum 158.Vt time_t 159value. 160In environments where the 161.Ev TZ 162environment variable names a TZif file, 163overflow can happen for either function for an argument sufficiently 164close to an extreme 165.Vt time_t 166value if the TZif file specifies unrealistic leap second corrections. 167.El 168.Sh "SEE ALSO" 169.Xr difftime 3 , 170.Xr localtime 3 , 171.Xr mktime 3 , 172.Xr time 3 173