1.\" $NetBSD: time2posix.3,v 1.11 2002/02/07 07:00:34 ross Exp $ 2.Dd April 1, 2001 3.Dt TIME2POSIX 3 4.Os 5.Sh NAME 6.Nm time2posix , 7.Nm posix2time 8.Nd convert seconds since the Epoch 9.Sh LIBRARY 10.Lb libc 11.Sh SYNOPSIS 12.Fd #include \*[Lt]time.h\*[Gt] 13.Ft time_t 14.Fn time2posix "time_t t" 15.Ft time_t 16.Fn posix2time "time_t t" 17.Sh DESCRIPTION 18.St -p1003.1 19legislates that a 20.Va time_t 21value of 536457599 shall correspond to 22.Dl Wed Dec 31 23:59:59 UTC 1986 . 23This effectively implies that POSIX 24.Va time_t Ns 's 25cannot include leap seconds and, therefore, 26that the system time must be adjusted as each leap occurs. 27.Pp 28If the time package is configured with leap-second support 29enabled, however, no such adjustment is needed and 30.Va time_t 31values 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 37.Va time_t 38is intended to be (mostly) 39opaque \(em 40.Va time_t 41values should only be obtained-from and 42passed-to functions such as 43.Xr time 3 , 44.Xr localtime 3 , 45.Xr mktime 3 , 46and 47.Xr difftime 3 . 48However, POSIX gives an arithmetic expression for directly computing a 49.Va time_t 50value from a given date/time, and the same relationship is assumed by 51some (usually older) applications. Any programs creating/dissecting 52.Va time_t Ns 's 53using such a relationship will typically not handle intervals over 54leap seconds correctly. 55.Pp 56The 57.Fn time2posix 58and 59.Fn posix2time 60functions are provided to address this 61.Va time_t 62mismatch by converting between local 63.Va time_t 64values and their POSIX equivalents. This is done by accounting for the 65number of time-base changes that would have taken place on a POSIX 66system as leap seconds were inserted or deleted. These converted 67values can then be used in lieu of correcting the older applications, 68or when communicating with POSIX-compliant systems. 69.Pp 70.Fn time2posix 71is single-valued. That is, every local 72.Va time_t 73corresponds to a single POSIX 74.Va time_t . 75.Fn posix2time 76is less well-behaved: for a positive leap second hit the result is not 77unique, and for a negative leap second hit the corresponding POSIX 78.Va time_t 79doesn't exist so an adjacent value is returned. Both of these are good 80indicators of the inferiority of the POSIX representation. 81.Pp 82The following table summarizes the relationship between a 83.Va time_t 84and its conversion to, and back from, the POSIX representation over 85the leap second inserted at the end of June, 1993. 86.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X) -offset indent 87.It Sy DATE TIME T X=time2posix(T) posix2time(X) 88.It 93/06/30 23:59:59 A+0 B+0 A+0 89.It 93/06/30 23:59:60 A+1 B+1 A+1 or A+2 90.It 93/07/01 00:00:00 A+2 B+1 A+1 or A+2 91.It 93/07/01 00:00:01 A+3 B+2 A+3 92.El 93.Pp 94A leap second deletion would look like... 95.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X) -offset indent 96.It Sy DATE TIME T X=time2posix(T) posix2time(X) 97.It ??/06/30 23:59:58 A+0 B+0 A+0 98.It ??/07/01 00:00:00 A+1 B+2 A+1 99.It ??/07/01 00:00:01 A+2 B+3 A+2 100.El 101[Note: posix2time(B+1) =\*[Gt] A+0 or A+1] 102.Pp 103If leap-second support is not enabled, local 104.Va time_t Ns 's 105and POSIX 106.Va time_t Ns 's 107are equivalent, and both 108.Fn time2posix 109and 110.Fn posix2time 111degenerate to the identity function. 112.Sh SEE ALSO 113.Xr difftime 3 , 114.Xr localtime 3 , 115.Xr mktime 3 , 116.Xr time 3 117.\" @(#)time2posix.3 7.7 118.\" This file is in the public domain, so clarified as of 119.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov). 120