1.\" $OpenBSD: time2posix.3,v 1.20 2015/02/23 19:05:36 bentley Exp $ 2.Dd $Mdocdate: February 23 2015 $ 3.Dt TIME2POSIX 3 4.Os 5.Sh NAME 6.Nm time2posix , 7.Nm posix2time 8.Nd convert seconds since the Epoch 9.Sh SYNOPSIS 10.In sys/types.h 11.In time.h 12.Ft time_t 13.Fn time2posix "time_t t" 14.Ft time_t 15.Fn posix2time "time_t t" 16.Sh DESCRIPTION 17.St -p1003.1 18legislates that a 19.Vt time_t 20value of 21536457599 shall correspond to 22.Dq Wed Dec 31 23:59:59 UTC 1986 . 23This effectively implies that a POSIX 24.Vt time_t 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, 30however, 31no such adjustment is needed and 32.Vt time_t 33values continue to increase over leap events 34.Po 35as a true 36.Sq seconds since... 37value 38.Pc . 39This means that these values will differ from those required by POSIX 40by the net number of leap seconds inserted since the Epoch. 41.Pp 42Typically this is not a problem as the type 43.Vt time_t 44is intended to be 45.Pq mostly 46opaque. 47.Vt time_t 48values should only be obtained from and 49passed to functions such as 50.Xr time 3 , 51.Xr localtime 3 , 52.Xr mktime 3 , 53and 54.Xr difftime 3 . 55However, 56POSIX gives an arithmetic 57expression for directly computing a 58.Vt time_t 59value from a given date/time, 60and the same relationship is assumed by some 61.Pq usually older 62applications. 63Any programs creating/dissecting 64.Vt time_t 65values 66using such a relationship will typically not handle intervals 67over leap seconds correctly. 68.Pp 69The 70.Fn time2posix 71and 72.Fn posix2time 73functions are provided to address this 74.Vt time_t 75mismatch by converting 76between local 77.Vt time_t 78values and their POSIX equivalents. 79This is done by accounting for the number of time-base changes that 80would have taken place on a POSIX system as leap seconds were inserted 81or deleted. 82These converted values can then be used in lieu of correcting the older 83applications, 84or when communicating with POSIX-compliant systems. 85.Pp 86.Fn time2posix 87is single-valued. 88That is, 89every local 90.Vt time_t 91corresponds to a single POSIX 92.Vt time_t . 93.Fn posix2time 94is less well-behaved: 95for a positive leap second hit the result is not unique, 96and for a negative leap second hit the corresponding 97POSIX 98.Vt time_t 99doesn't exist so an adjacent value is returned. 100Both of these are good indicators of the inferiority of the 101POSIX representation. 102.Pp 103The following table summarizes the relationship between a time 104T and its conversion to, 105and back from, 106the POSIX representation over the leap second inserted at the end of June, 1071993. 108.Bl -column 93/06/30 23:59:59 A+0 X=time2posix(T) posix2time(X) -offset indent 109.It Em DATE Ta Em TIME Ta Em T Ta Em X=time2posix(T) Ta Em posix2time(X) 110.It 93/06/30 Ta 23:59:59 Ta A+0 Ta B+0 Ta A+0 111.It 93/06/30 Ta 23:59:60 Ta A+1 Ta B+1 Ta A+1 or A+2 112.It 93/07/01 Ta 00:00:00 Ta A+2 Ta B+1 Ta A+1 or A+2 113.It 93/07/01 Ta 00:00:01 Ta A+3 Ta B+2 Ta A+3 114.El 115.Pp 116A leap second deletion would look like... 117.Bl -column ??/06/30 23:59:58 A+0 X=time2posix(T) posix2time(X) -offset indent 118.It Em DATE Ta Em TIME Ta Em T Ta Em X=time2posix(T) Ta Em posix2time(X) 119.It ??/06/30 Ta 23:59:58 Ta A+0 Ta B+0 Ta A+0 120.It ??/07/01 Ta 00:00:00 Ta A+1 Ta B+2 Ta A+1 121.It ??/07/01 Ta 00:00:01 Ta A+2 Ta B+3 Ta A+2 122.El 123.Pp 124[Note: posix2time(B+1) => A+0 or A+1] 125.Pp 126If leap-second support is not enabled, local 127.Vt time_t 128and 129POSIX 130.Vt time_t 131are equivalent, and both 132.Fn time2posix 133and 134.Fn posix2time 135degenerate to the identity function. 136.Sh SEE ALSO 137.Xr difftime 3 , 138.Xr localtime 3 , 139.Xr mktime 3 , 140.Xr time 3 141.\" This file is in the public domain, so clarified as of 142.\" 1996-06-05 by Arthur David Olson. 143