.\"	$OpenBSD: time2posix.3,v 1.19 2013/06/05 03:39:23 tedu Exp $
.Dd $Mdocdate: June 5 2013 $
.Dt TIME2POSIX 3
.Os
.Sh NAME
.Nm time2posix ,
.Nm posix2time
.Nd convert seconds since the Epoch
.Sh SYNOPSIS
.In sys/types.h
.In time.h
.Ft time_t
.Fn time2posix "time_t t"
.Ft time_t
.Fn posix2time "time_t t"
.Sh DESCRIPTION
.St -p1003.1
legislates that a
.Fa time_t
value of
536457599 shall correspond to "Wed Dec 31 23:59:59 UTC 1986."
This effectively implies that a POSIX
.Fa time_t
cannot include leap seconds and, therefore,
that the system time must be adjusted as each leap occurs.
.Pp
If the time package is configured with leap-second support
enabled,
however,
no such adjustment is needed and
.Fa time_t
values continue to increase over leap events
.Po
as a true
.Sq seconds since...
value
.Pc .
This means that these values will differ from those required by POSIX
by the net number of leap seconds inserted since the Epoch.
.Pp
Typically this is not a problem as the type
.Fa time_t
is intended to be
.Pq mostly
opaque.
.Fa time_t
values should only be obtained from and
passed to functions such as
.Xr time 3 ,
.Xr localtime 3 ,
.Xr mktime 3 ,
and
.Xr difftime 3 .
However,
POSIX gives an arithmetic
expression for directly computing a
.Fa time_t
value from a given date/time,
and the same relationship is assumed by some
.Pq usually older
applications.
Any programs creating/dissecting
.Fa time_t
values
using such a relationship will typically not handle intervals
over leap seconds correctly.
.Pp
The
.Fn time2posix
and
.Fn posix2time
functions are provided to address this
.Fa time_t
mismatch by converting
between local
.Fa time_t
values and their POSIX equivalents.
This is done by accounting for the number of time-base changes that
would have taken place on a POSIX system as leap seconds were inserted
or deleted.
These converted values can then be used in lieu of correcting the older
applications,
or when communicating with POSIX-compliant systems.
.Pp
.Fn time2posix
is single-valued.
That is,
every local
.Fa time_t
corresponds to a single POSIX
.Fa time_t .
.Fn posix2time
is less well-behaved:
for a positive leap second hit the result is not unique,
and for a negative leap second hit the corresponding
POSIX
.Fa time_t
doesn't exist so an adjacent value is returned.
Both of these are good indicators of the inferiority of the
POSIX representation.
.Pp
The following table summarizes the relationship between a time
T and its conversion to,
and back from,
the POSIX representation over the leap second inserted at the end of June,
1993.
.Bd -ragged -offset indent
.ta \w'93/06/30 'u +\w'23:59:59 'u +\w'A+0 'u +\w'X=time2posix(T) 'u
DATE	TIME	T	X=time2posix(T)	posix2time(X)
93/06/30	23:59:59	A+0	B+0	A+0
93/06/30	23:59:60	A+1	B+1	A+1 or A+2
93/07/01	00:00:00	A+2	B+1	A+1 or A+2
93/07/01	00:00:01	A+3	B+2	A+3
.sp
A leap second deletion would look like...
.sp
DATE	TIME	T	X=time2posix(T)	posix2time(X)
??/06/30	23:59:58	A+0	B+0	A+0
??/07/01	00:00:00	A+1	B+2	A+1
??/07/01	00:00:01	A+2	B+3	A+2
.sp
.ce
	[Note: posix2time(B+1) => A+0 or A+1]
.Ed
.Pp
If leap-second support is not enabled, local
.Fa time_t
and
POSIX
.Fa time_t
are equivalent, and both
.Fn time2posix
and
.Fn posix2time
degenerate to the identity function.
.Sh SEE ALSO
.Xr difftime 3 ,
.Xr localtime 3 ,
.Xr mktime 3 ,
.Xr time 3
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson.