[BACK]Return to time2posix.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

File: [cvs.NetBSD.org] / src / lib / libc / time / time2posix.3 (download)

Revision 1.13, Wed Apr 16 13:34:58 2003 UTC (18 years ago) by wiz
Branch: MAIN
CVS Tags: yamt-pf42-baseX, yamt-pf42-base4, yamt-pf42-base3, yamt-pf42-base2, yamt-pf42-base, yamt-pf42, wrstuden-revivesa-base-3, wrstuden-revivesa-base-2, wrstuden-revivesa-base-1, wrstuden-revivesa-base, wrstuden-revivesa, wrstuden-fixsa-newbase, wrstuden-fixsa-base-1, wrstuden-fixsa-base, wrstuden-fixsa, netbsd-5-base, netbsd-5-2-RELEASE, netbsd-5-2-RC1, netbsd-5-2-3-RELEASE, netbsd-5-2-2-RELEASE, netbsd-5-2-1-RELEASE, netbsd-5-2, netbsd-5-1-RELEASE, netbsd-5-1-RC4, netbsd-5-1-RC3, netbsd-5-1-RC2, netbsd-5-1-RC1, netbsd-5-1-5-RELEASE, netbsd-5-1-4-RELEASE, netbsd-5-1-3-RELEASE, netbsd-5-1-2-RELEASE, netbsd-5-1-1-RELEASE, netbsd-5-1, netbsd-5-0-RELEASE, netbsd-5-0-RC4, netbsd-5-0-RC3, netbsd-5-0-RC2, netbsd-5-0-RC1, netbsd-5-0-2-RELEASE, netbsd-5-0-1-RELEASE, netbsd-5-0, netbsd-5, netbsd-4-base, netbsd-4-0-RELEASE, netbsd-4-0-RC5, netbsd-4-0-RC4, netbsd-4-0-RC3, netbsd-4-0-RC2, netbsd-4-0-RC1, netbsd-4-0-1-RELEASE, netbsd-4-0, netbsd-4, netbsd-3-base, netbsd-3-1-RELEASE, netbsd-3-1-RC4, netbsd-3-1-RC3, netbsd-3-1-RC2, netbsd-3-1-RC1, netbsd-3-1-1-RELEASE, netbsd-3-1, netbsd-3-0-RELEASE, netbsd-3-0-RC6, netbsd-3-0-RC5, netbsd-3-0-RC4, netbsd-3-0-RC3, netbsd-3-0-RC2, netbsd-3-0-RC1, netbsd-3-0-3-RELEASE, netbsd-3-0-2-RELEASE, netbsd-3-0-1-RELEASE, netbsd-3-0, netbsd-3, netbsd-2-base, netbsd-2-1-RELEASE, netbsd-2-1-RC6, netbsd-2-1-RC5, netbsd-2-1-RC4, netbsd-2-1-RC3, netbsd-2-1-RC2, netbsd-2-1-RC1, netbsd-2-1, netbsd-2-0-base, netbsd-2-0-RELEASE, netbsd-2-0-RC5, netbsd-2-0-RC4, netbsd-2-0-RC3, netbsd-2-0-RC2, netbsd-2-0-RC1, netbsd-2-0-3-RELEASE, netbsd-2-0-2-RELEASE, netbsd-2-0-1-RELEASE, netbsd-2-0, netbsd-2, mjf-devfs2-base, mjf-devfs2, matt-nb5-pq3-base, matt-nb5-pq3, matt-nb5-mips64-u2-k2-k4-k7-k8-k9, matt-nb5-mips64-u1-k1-k5, matt-nb5-mips64-premerge-20101231, matt-nb5-mips64-premerge-20091211, matt-nb5-mips64-k15, matt-nb5-mips64, matt-nb4-mips64-k7-u2a-k9b, matt-mips64-base2, matt-mips64-base, matt-mips64, matt-armv6-prevmlocking, matt-armv6-nbase, matt-armv6-base, matt-armv6, keiichi-mipv6-base, keiichi-mipv6, hpcarm-cleanup-nbase, hpcarm-cleanup-base, hpcarm-cleanup, cube-autoconf-base, cube-autoconf, christos-time_t-nbase, christos-time_t-base, christos-time_t, abandoned-netbsd-4-base, abandoned-netbsd-4
Branch point for: jym-xensuspend
Changes since 1.12: +2 -2 lines

.In header.h
instead of
.Fd #include \*[Lt]header.h\*[Gt]
Much easier to read and write, and supported by groff for ages.
Okayed by ross.

.\"	$NetBSD: time2posix.3,v 1.13 2003/04/16 13:34:58 wiz Exp $
.Dd April 1, 2001
.Nm time2posix ,
.Nm posix2time
.Nd convert seconds since the Epoch
.Lb libc
.In time.h
.Ft time_t
.Fn time2posix "time_t t"
.Ft time_t
.Fn posix2time "time_t t"
.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.
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.
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 ,
.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.
.Fn time2posix
.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.
.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
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
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
[Note: posix2time(B+1) =\*[Gt] A+0 or A+1]
If leap-second support is not enabled, local
.Va time_t Ns 's
.Va time_t Ns 's
are equivalent, and both
.Fn time2posix
.Fn posix2time
degenerate to the identity function.
.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).