1.\" $NetBSD: time2posix.3,v 1.12 2002/10/01 18:16:00 wiz 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. 52Any programs creating/dissecting 53.Va time_t Ns 's 54using such a relationship will typically not handle intervals over 55leap seconds correctly. 56.Pp 57The 58.Fn time2posix 59and 60.Fn posix2time 61functions are provided to address this 62.Va time_t 63mismatch by converting between local 64.Va time_t 65values and their POSIX equivalents. 66This is done by accounting for the number of time-base changes that would 67have taken place on a POSIX system as leap seconds were inserted or deleted. 68These converted values can then be used in lieu of correcting the 69older applications, or when communicating with POSIX-compliant systems. 70.Pp 71.Fn time2posix 72is single-valued. 73That is, every local 74.Va time_t 75corresponds to a single POSIX 76.Va time_t . 77.Fn posix2time 78is less well-behaved: for a positive leap second hit the result is not 79unique, and for a negative leap second hit the corresponding POSIX 80.Va time_t 81doesn't exist so an adjacent value is returned. 82Both of these are good indicators of the inferiority of the POSIX 83representation. 84.Pp 85The following table summarizes the relationship between a 86.Va time_t 87and its conversion to, and back from, the POSIX representation over 88the leap second inserted at the end of June, 1993. 89.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X) -offset indent 90.It Sy DATE TIME T X=time2posix(T) posix2time(X) 91.It 93/06/30 23:59:59 A+0 B+0 A+0 92.It 93/06/30 23:59:60 A+1 B+1 A+1 or A+2 93.It 93/07/01 00:00:00 A+2 B+1 A+1 or A+2 94.It 93/07/01 00:00:01 A+3 B+2 A+3 95.El 96.Pp 97A leap second deletion would look like... 98.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X) -offset indent 99.It Sy DATE TIME T X=time2posix(T) posix2time(X) 100.It ??/06/30 23:59:58 A+0 B+0 A+0 101.It ??/07/01 00:00:00 A+1 B+2 A+1 102.It ??/07/01 00:00:01 A+2 B+3 A+2 103.El 104[Note: posix2time(B+1) =\*[Gt] A+0 or A+1] 105.Pp 106If leap-second support is not enabled, local 107.Va time_t Ns 's 108and POSIX 109.Va time_t Ns 's 110are equivalent, and both 111.Fn time2posix 112and 113.Fn posix2time 114degenerate to the identity function. 115.Sh SEE ALSO 116.Xr difftime 3 , 117.Xr localtime 3 , 118.Xr mktime 3 , 119.Xr time 3 120.\" @(#)time2posix.3 7.7 121.\" This file is in the public domain, so clarified as of 122.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov). 123