120 lines
3.5 KiB
Groff
120 lines
3.5 KiB
Groff
.\" $NetBSD: time2posix.3,v 1.10 2001/04/07 16:14:44 kleink Exp $
|
|
.Dd April 1, 2001
|
|
.Dt TIME2POSIX 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm time2posix ,
|
|
.Nm posix2time
|
|
.Nd convert seconds since the Epoch
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include <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
|
|
.Va time_t
|
|
value of 536457599 shall correspond to
|
|
.Dl Wed Dec 31 23:59:59 UTC 1986 .
|
|
This effectively implies that POSIX
|
|
.Va time_t Ns 's
|
|
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
|
|
.Va time_t
|
|
values continue to increase over leap events
|
|
(as a true `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
|
|
.Va time_t
|
|
is intended to be (mostly)
|
|
opaque \(em
|
|
.Va 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
|
|
.Va time_t
|
|
value from a given date/time, and the same relationship is assumed by
|
|
some (usually older) applications. Any programs creating/dissecting
|
|
.Va time_t Ns 's
|
|
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
|
|
.Va time_t
|
|
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 in lieu of correcting the older applications,
|
|
or when communicating with POSIX-compliant systems.
|
|
.Pp
|
|
.Fn time2posix
|
|
is single-valued. That is, every local
|
|
.Va time_t
|
|
corresponds to a single POSIX
|
|
.Va 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
|
|
.Va 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
|
|
.Va 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)" "posix2time(X) -offset indent
|
|
.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)" "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 Ns 's
|
|
and POSIX
|
|
.Va time_t Ns 's
|
|
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
|
|
.\" @(#)time2posix.3 7.7
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).
|