.\"	$NetBSD: time2posix.3,v 1.24 2026/03/08 21:04:54 christos Exp $
.\" @(#)time2posix.3	7.7
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson.
.Dd March 8, 2026
.Dt TIME2POSIX 3
.Os
.Sh NAME
.Nm time2posix ,
.Nm time2posix_z ,
.Nm posix2time ,
.Nm posix2time_z
.Nd convert seconds since the Epoch
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In time.h
.Ft time_t
.Fn time2posix "time_t t"
.Ft time_t
.Fn time2posix_z "const timezone_t tz" "time_t t"
.Ft time_t
.Fn posix2time "time_t t"
.Ft time_t
.Fn posix2time_z "const timezone_t tz" "time_t t"
.Sh DESCRIPTION
.St -p1003.1
says that
.Va time_t
values cannot count 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
.Va time_t
values continue to increase over leap events
(as a true
.Dq "seconds since..."
value).
This means that these values will differ from those required by POSIX
by the net number of leap seconds inserted since the Epoch.
.Pp
For many C programs this is not a problem as the C standard says that
.Va time_t
is 
(mostly)
opaque \(em
.Va time_t
values should be obtainedfrom and
passedto functions such as
.Xr time 3 ,
.Xr localtime 3 ,
.Xr localtime_r 3 ,
.Xr localtime_rz 3 ,
.Xr mktime 3 ,
.Xr mktime_z 3 ,
and
.Xr difftime 3 .
However, POSIX gives an arithmetic expression for computing a
.Va time_t
value directly given Universal date and time,
and the same relationship is assumed by
some applications.
Any programs creating/dissecting
.Va time_t
values using such a relationship will typically not handle intervals over
leap seconds correctly.
.Pp
The
.Fn time2posix ,
.Fn time2posix_z ,
.Fn posix2time ,
and
.Fn posix2time_z
+functions address this mismatch by converting
between local
.Va 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
when communicating with POSIX-compliant systems.
.Pp
The
.Fn time2posix
and
.Fn time2posix_z
functions convert a
.Va time_t .
value to its POSIX counterpart, if one exists.
The
.Fn posix2time
and
.Fn posix2time
does the reverse but
are less well-behaved:
for a positive leap second hit the result is not unique,
and for a negative leap second hit the corresponding
POSIX
.Va time_t
doesn't exist so an adjacent value is returned.
Both these indicate problems with the
POSIX representation.
.Pp
The
.Dq z
variants of the two functions behave exactly like their counterparts,
but they operate in the given
.Fa tz
argument which was previously allocated using
.Xr tzalloc 3
and are re-entrant.
.Pp
The following table summarizes the relationship between a
.Va time_t
and its conversion to, and back from, the POSIX representation over
the leap second inserted at the end of June, 1993.
In this table, X=time2posix(T), Y=posix2time(X), A=741484816, and B=A\-17
because 17 positive leap seconds preceded this leap second.
.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
.It Sy DATE	TIME	T	X=time2posix(T)	posix2time(X)
.It 1993-06-30	23:59:59	A+0	B+0	A+0
.It 1993-06-30	23:59:60	A+1	B+1	A+1 or A+2
.It 1993-07-01	00:00:00	A+2	B+1	A+1 or A+2
.It 1993-07-01	00:00:01	A+3	B+2	A+3
.El
.Pp
A leap second deletion would look like...
.Bl -column "??/06/30" "23:59:58" "A+0" "X=time2posix(T)" "posix2time(X)" -offset indent
.It Sy DATE	TIME	T	X=time2posix(T)	posix2time(X)
.It ????-06-30	23:59:58	A+0	B+0	A+0
.It ????-07-01	00:00:00	A+1	B+2	A+1
.It ????-07-01	00:00:01	A+2	B+3	A+2
.El
[Note: posix2time(B+1) => A+0 or A+1]
.Pp
If leap-second support is not enabled, local
.Va time_t
and
POSIX
.Va time_t
values are equivalent,
and both
.Fn time2posix
and
.Fn posix2time
degenerate to the identity function.
+.Sh "RETURN VALUE"
If successful, these functions return the resulting timestamp without modifying
.Va errno .
Otherwise, they set
.Va errno
and return
.Va "((time_t) -1)" .
.Sh ERRORS
These functions fail if:
.Bl -tag -width Er
.It Bq Er EOVERFLOW
The resulting value cannot be represented.
This can happen for
.Fn posix2time
if its argument is close to the maximum
.Va time_t
value.
In environments where the
.Ev TZ
environment variable names a TZif file,
overflow can happen for either function for an argument sufficiently
close to an extreme
.Va time_t
value if the TZif file specifies unrealistic leap second corrections.
.El
.Sh SEE ALSO
.Xr difftime 3 ,
.Xr localtime 3 ,
.Xr localtime_r 3 ,
.Xr localtime_rz 3 ,
.Xr mktime 3 ,
.Xr mktime_z 3 ,
.Xr time 3 ,
.Xr tzalloc 3

.