1.\" $OpenBSD: time2posix.3,v 1.15 2007/05/31 19:19:34 jmc Exp $ 2.Dd $Mdocdate: May 31 2007 $ 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 17.St -p1003.1 18legislates that a 19.Fa time_t 20value of 21536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986." 22This effectively implies that a POSIX 23.Fa time_t 24cannot include leap seconds and, therefore, 25that the system time must be adjusted as each leap occurs. 26.Pp 27If the time package is configured with leap-second support 28enabled, 29however, 30no such adjustment is needed and 31.Fa time_t 32values continue to increase over leap events 33.Po 34as a true 35.Sq seconds since... 36value 37.Pc . 38This means that these values will differ from those required by POSIX 39by the net number of leap seconds inserted since the Epoch. 40.Pp 41Typically this is not a problem as the type 42.Fa time_t 43is intended to be 44.Pq mostly 45opaque. 46.Fa time_t 47values should only be obtained from and 48passed to functions such as 49.Xr time 3 , 50.Xr localtime 3 , 51.Xr mktime 3 , 52and 53.Xr difftime 3 . 54However, 55POSIX gives an arithmetic 56expression for directly computing a 57.Fa time_t 58value from a given date/time, 59and the same relationship is assumed by some 60.Pq usually older 61applications. 62Any programs creating/dissecting 63.Fa time_t 64values 65using such a relationship will typically not handle intervals 66over leap seconds correctly. 67.Pp 68The 69.Fn time2posix 70and 71.Fn posix2time 72functions are provided to address this 73.Fa time_t 74mismatch by converting 75between local 76.Fa time_t 77values and their POSIX equivalents. 78This is done by accounting for the number of time-base changes that 79would have taken place on a POSIX system as leap seconds were inserted 80or deleted. 81These converted values can then be used in lieu of correcting the older 82applications, 83or when communicating with POSIX-compliant systems. 84.Pp 85.Fn time2posix 86is single-valued. 87That is, 88every local 89.Fa time_t 90corresponds to a single POSIX 91.Fa time_t . 92.Fn posix2time 93is less well-behaved: 94for a positive leap second hit the result is not unique, 95and for a negative leap second hit the corresponding 96POSIX 97.Fa time_t 98doesn't exist so an adjacent value is returned. 99Both of these are good indicators of the inferiority of the 100POSIX representation. 101.Pp 102The following table summarizes the relationship between a time 103T and its conversion to, 104and back from, 105the POSIX representation over the leap second inserted at the end of June, 1061993. 107.Bd -ragged -offset indent 108.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u 109DATE TIME T X=time2posix(T) posix2time(X) 11093/06/30 23:59:59 A+0 B+0 A+0 11193/06/30 23:59:60 A+1 B+1 A+1 or A+2 11293/07/01 00:00:00 A+2 B+1 A+1 or A+2 11393/07/01 00:00:01 A+3 B+2 A+3 114 115A leap second deletion would look like... 116 117DATE TIME T X=time2posix(T) posix2time(X) 118??/06/30 23:59:58 A+0 B+0 A+0 119??/07/01 00:00:00 A+1 B+2 A+1 120??/07/01 00:00:01 A+2 B+3 A+2 121.sp 122.ce 123 [Note: posix2time(B+1) => A+0 or A+1] 124.Ed 125.Pp 126If leap-second support is not enabled, local 127.Fa time_t 128and 129POSIX 130.Fa 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.\" @(#)time2posix.3 8.1 142.\" This file is in the public domain, so clarified as of 143.\" 1996-06-05 by Arthur David Olson. 144