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