1.\" $OpenBSD: time2posix.3,v 1.11 2003/05/07 08:52:42 jmc Exp $ 2.Dd May 24, 1999 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.Fd #include <sys/types.h> 11.Fd #include <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 17IEEE Standard 1003.1 18(POSIX) 19legislates that a 20.Fa time_t 21value of 22536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986." 23This effectively implies that a POSIX 24.Fa 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.Fa 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.Fa time_t 44is intended to be 45.Pq mostly 46opaque. 47.Fa 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.Fa 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.Fa 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.Fa time_t 75mismatch by converting 76between local 77.Fa 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.Fa time_t 91corresponds to a single POSIX 92.Fa 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.Fa 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.Bd -ragged -offset indent 109.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u 110DATE TIME T X=time2posix(T) posix2time(X) 11193/06/30 23:59:59 A+0 B+0 A+0 11293/06/30 23:59:60 A+1 B+1 A+1 or A+2 11393/07/01 00:00:00 A+2 B+1 A+1 or A+2 11493/07/01 00:00:01 A+3 B+2 A+3 115 116A leap second deletion would look like... 117 118DATE TIME T X=time2posix(T) posix2time(X) 119??/06/30 23:59:58 A+0 B+0 A+0 120??/07/01 00:00:00 A+1 B+2 A+1 121??/07/01 00:00:01 A+2 B+3 A+2 122.sp 123.ce 124 [Note: posix2time(B+1) => A+0 or A+1] 125.Ed 126.Pp 127If leap-second support is not enabled, local 128.Fa time_t 129and 130POSIX 131.Fa time_t 132are equivalent, and both 133.Fn time2posix 134and 135.Fn posix2time 136degenerate to the identity function. 137.Sh SEE ALSO 138.Xr difftime 3 , 139.Xr localtime 3 , 140.Xr mktime 3 , 141.Xr time 3 142.\" @(#)time2posix.3 7.7 143.\" This file is in the public domain, so clarified as of 144.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov). 145