1.\" $FreeBSD: head/contrib/tzcode/stdtime/time2posix.3 192890 2009-05-27 12:18:39Z edwin $ 2.\" 3.Dd October 19, 2008 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 20legislates that a time_t value of 21536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986." 22This effectively implies that POSIX time_t's cannot include 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 31time_t values continue to increase over leap events 32(as a true `seconds since...' value). 33This means that these values will differ from those required by POSIX 34by the net number of leap seconds inserted since the Epoch. 35.Pp 36Typically this is not a problem as the type time_t is intended 37to be 38(mostly) 39opaque\(emtime_t values should only be obtained-from and 40passed-to functions such as 41.Xr time 3 , 42.Xr localtime 3 , 43.Xr mktime 3 44and 45.Xr difftime 3 . 46However, 47.St -p1003.1-88 48gives an arithmetic 49expression for directly computing a time_t value from a given date/time, 50and the same relationship is assumed by some 51(usually older) 52applications. 53Any programs creating/dissecting time_t's 54using such a relationship will typically not handle intervals 55over leap seconds correctly. 56.Pp 57The 58.Fn time2posix 59and 60.Fn posix2time 61functions are provided to address this time_t mismatch by converting 62between local time_t values and their POSIX equivalents. 63This is done by accounting for the number of time-base changes that 64would have taken place on a POSIX system as leap seconds were inserted 65or deleted. 66These converted values can then be used in lieu of correcting the older 67applications, 68or when communicating with POSIX-compliant systems. 69.Pp 70The 71.Fn time2posix 72function is single-valued. 73That is, 74every local time_t 75corresponds to a single POSIX time_t. 76The 77.Fn posix2time 78function is less well-behaved: 79for a positive leap second hit the result is not unique, 80and for a negative leap second hit the corresponding 81POSIX time_t does not exist so an adjacent value is returned. 82Both of these are good indicators of the inferiority of the 83POSIX representation. 84.Pp 85The following table summarizes the relationship between time_t 86and its conversion to, 87and back from, 88the POSIX representation over the leap second inserted at the end of June, 891993. 90.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" 91.It Sy "DATE TIME T X=time2posix(T) posix2time(X)" 92.It "93/06/30 23:59:59 A+0 B+0 A+0" 93.It "93/06/30 23:59:60 A+1 B+1 A+1 or A+2" 94.It "93/07/01 00:00:00 A+2 B+1 A+1 or A+2" 95.It "93/07/01 00:00:01 A+3 B+2 A+3" 96.El 97.Pp 98A leap second deletion would look like... 99.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" 100.It Sy "DATE TIME T X=time2posix(T) posix2time(X)" 101.It "??/06/30 23:59:58 A+0 B+0 A+0" 102.It "??/07/01 00:00:00 A+1 B+2 A+1" 103.It "??/07/01 00:00:01 A+2 B+3 A+2" 104.El 105.Pp 106.D1 No "[Note: posix2time(B+1) => A+0 or A+1]" 107.Pp 108If leap-second support is not enabled, 109local time_t's and 110POSIX time_t's are equivalent, 111and both 112.Fn time2posix 113and 114.Fn posix2time 115degenerate to the identity function. 116.Sh "SEE ALSO" 117.Xr difftime 3 , 118.Xr localtime 3 , 119.Xr mktime 3 , 120.Xr time 3 121.\" This file is in the public domain, so clarified as of 122.\" 1996-06-05 by Arthur David Olson. 123