75411d1572
MFC after: 3 weeks Sponsored by: Klara, Inc. Reviewed by: philip Differential Revision: https://reviews.freebsd.org/D39712
147 lines
3.4 KiB
Groff
147 lines
3.4 KiB
Groff
.\" This file is in the public domain, so clarified as of
|
|
.\" 1996-06-05 by Arthur David Olson.
|
|
.Dd December 15, 2022
|
|
.Dt TIME2POSIX 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm time2posix ,
|
|
.Nm posix2time
|
|
.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 posix2time "time_t t"
|
|
.Sh DESCRIPTION
|
|
.St -p1003.1-88
|
|
requires the time_t value 536457599 to stand for 1986-12-31 23:59:59 UTC.
|
|
This effectively implies that POSIX
|
|
.Vt time_t
|
|
values 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
|
|
.Vt 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
|
|
Typically this is not a problem as the type
|
|
.Vt time_t
|
|
is intended
|
|
to be
|
|
(mostly)
|
|
opaque \(em
|
|
.Vt 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,
|
|
.St -p1003.1-88
|
|
gives an arithmetic
|
|
expression for directly computing a
|
|
.Vt time_t
|
|
value from a given date/time,
|
|
and the same relationship is assumed by some
|
|
(usually older)
|
|
applications.
|
|
Any programs creating/dissecting
|
|
.Vt 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
|
|
.Vt time_t
|
|
mismatch by converting
|
|
between local
|
|
.Vt 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
|
|
The
|
|
.Fn time2posix
|
|
function
|
|
is single-valued.
|
|
That is,
|
|
every local
|
|
.Vt time_t
|
|
corresponds to a single POSIX
|
|
.Vt time_t .
|
|
The
|
|
.Fn posix2time
|
|
function
|
|
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
|
|
.Vt time_t
|
|
does not 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.
|
|
.Bl -column "93/06/30" "23:59:59" "A+0" "X=time2posix(T)"
|
|
.It Sy "DATE TIME T X=time2posix(T) posix2time(X)"
|
|
.It "93/06/30 23:59:59 A+0 B+0 A+0"
|
|
.It "93/06/30 23:59:60 A+1 B+1 A+1 or A+2"
|
|
.It "93/07/01 00:00:00 A+2 B+1 A+1 or A+2"
|
|
.It "93/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)"
|
|
.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
|
|
.Pp
|
|
.D1 No "[Note: posix2time(B+1) => A+0 or A+1]"
|
|
.Pp
|
|
If leap-second support is not enabled,
|
|
local
|
|
.Vt time_t
|
|
and
|
|
POSIX
|
|
.Vt time_t
|
|
values 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
|