[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.6, Wed Jun 18 01:12:54 1997 UTC (23 years, 1 month ago) by jtc
Branch: MAIN
CVS Tags: netbsd-1-3-base, netbsd-1-3-RELEASE, netbsd-1-3-PATCH003-CANDIDATE2, netbsd-1-3-PATCH003-CANDIDATE1, netbsd-1-3-PATCH003-CANDIDATE0, netbsd-1-3-PATCH003, netbsd-1-3-PATCH002, netbsd-1-3-PATCH001, netbsd-1-3-BETA, netbsd-1-3
Changes since 1.5: +3 -3 lines

Sync with tzcode1997e

.\"	$NetBSD: time2posix.3,v 1.6 1997/06/18 01:12:54 jtc Exp $
time2posix, posix2time \- convert seconds since the Epoch
.B #include <sys/types.h>
.B #include <time.h>
.B time_t time2posix(t)
.B time_t t
.B time_t posix2time(t)
.B time_t t
IEEE Standard 1003.1
legislates that a time_t value of
536457599 shall correspond to "Wed Dec 31 23:59:59 GMT 1986."
This effectively implies that POSIX time_t's cannot include leap
seconds and,
that the system time must be adjusted as each leap occurs.
If the time package is configured with leap-second support
no such adjustment is needed and
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 time_t is intended
to be
opaque\(emtime_t values should only be obtained-from and
passed-to functions such as
.IR time(3) ,
.IR localtime(3) ,
.IR mktime(3) ,
.IR difftime(3) .
POSIX gives an arithmetic
expression for directly computing a time_t value from a given date/time,
and the same relationship is assumed by some
(usually older)
Any programs creating/dissecting time_t's
using such a relationship will typically not handle intervals
over leap seconds correctly.
.I time2posix
.I posix2time
functions are provided to address this time_t mismatch by converting
between local 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
or when communicating with POSIX-compliant systems.
.I Time2posix
is single-valued.
That is,
every local time_t
corresponds to a single POSIX time_t.
.I 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 time_t doesn't exist so an adjacent value is returned.
Both of these are good indicators of the inferiority of the
POSIX representation.
The following table summarizes the relationship between a time
T and it's conversion to,
and back from,
the POSIX representation over the leap second inserted at the end of June,
.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

A leap second deletion would look like...

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
	[Note: posix2time(B+1) => A+0 or A+1]
If leap-second support is not enabled,
local time_t's and
POSIX time_t's are equivalent,
and both
.I time2posix
.I posix2time
degenerate to the identity function.
.\" @(#)time2posix.3	7.6
.\" This file is in the public domain, so clarified as of
.\" 1996-06-05 by Arthur David Olson (arthur_david_olson@nih.gov).