bind/doc/man/time.man

.\"
.\" Copyright (C) 2000  Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this document for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" $Id: time.man,v 1.1 2000/06/01 03:19:06 jim Exp $
.\"
.Dd Jun 30, 2000
.Dt TIME 3
.Os BIND9 9
.ds vT BIND9 Programmer's Manual
.Sh NAME
.Nm time
.Nd time-related operations
.Sh SYNOPSIS
.Fd #include <config.h>
 
.Fd #include <errno.h>
.Fd #include <limits.h>
.Fd #include <time.h>
 
.Fd #include <sys/time.h>
 
.Fd #include <isc/string.h>
.Fd #include <isc/time.h>
.Fd #include <isc/util.h>
.Ft void
.Fo "isc_interval_set"
.Fa "isc_interval_t *i"
.Fa "unsigned int seconds"
.Fa "unsigned int nanoseconds"
.Fc
.Ft isc_boolean_t
.Fn isc_interval_iszero "isc_interval_t *"
.Ft void
.Fo isc_time_set
.Fa "isc_time_t *t"
.Fa "unsigned int seconds"
.Fa "unsigned int nanoseconds"
.Fc
.Ft void
.Fn isc_time_settoepoch "isc_time_t *t"
.Ft isc_boolean_t
.Fn isc_time_isepoch "isc_time_t *t"
.Ft isc_result_t
.Fn isc_time_now "isc_time_t *t"
.Ft isc_result_t
.Fn isc_time_nowplusinterval "isc_time_t *t, isc_interval_t *i
.Ft int
.Fn isc_time_compare "isc_time_t *t1, isc_time_t *t2"
.Ft isc_result_t
.Fn isc_time_add "isc_time_t *t, isc_interval_t *i, isc_time_t *result"
.Ft isc_result_t
.Fn isc_time_subtract "isc_time_t *t, isc_interval_t *i, isc_time_t *result"
.Ft isc_uint64_t
.Fn isc_time_microdiff "isc_time_t *t1, isc_time_t *t2"
.Ft isc_uint32_t
.Fn isc_time_seconds "isc_time_t *t"
.Ft isc_result_t
.Fn isc_time_secondsastimet "isc_time_t *t, time_t *secondsp"
.Ft isc_uint32_t
.Fn isc_time_nanoseconds "isc_time_t *t"
.Sh DESCRIPTION
These functions are used by the name server for any time-related activities.
They operate on the system's struct
.Nm time_t
and two local data structures:
.Bd -literal -offset indent
struct isc_interval {
        unsigned int seconds;
        unsigned int nanoseconds;
};

typedef struct isc_interval isc_interval_t;
.Ed
.Bd -literal -offset indent
struct isc_time {
        unsigned int seconds;
        unsigned int nanoseconds;
};

typedef struct isc_time isc_time_t; 
.Ed
The contents of these structures are private
and MUST NOT be accessed by callers directly.
Details have only been provided so that callers can avoid
dynamic allocation.
The elements of these structures should only be manipulated via the
following functions.
.Pp
The function
.Fn isc_interval_set
initialises the
.Nm isc_interval_t
pointed at by
.Fa *i .
The elements
.Nm seconds
and
.Nm
nanoseconds
are set to the values of
.Fa seconds
and
.Fa nanoseconds
respectively.
.Pp
.Fn isc_interval_iszero
returns
.Er ISC_TRUE
if
.Fa *i
is the zero interval.
This condition should hold when the desired amount of time until an
event associated with interval 
.Fa *i
has elapsed.
.Pp
.Fn isc_time_settoepoch
sets 
.Fa *t
to the time of the epoch.
On
.Ux
systems this is 0 hours, 0 minutes, 0 seconds, January 1, 1970 UTC.
.Pp
The function
.Fn isc_time_isepoch
returns
.Er ISC_TRUE
if the time in
.Fa *t
is equal to the epoch time: "time zero".
It returns
.Er ISC_FALSE
otherwise.
.Pp
The current absolute time of day is obtained from
.Fn isc_time_now .
On a successful call to this function, the structure pointed at by
.Fa *t
is set to the number of seconds and nanoseconds since the epoch.
.Pp
.Fn isc_time_nowplusinterval
sets 
.Fa *t
to the current time plus the interval specified in
.Fa *i .
.Pp
.Fn isc_time_compare
compares the times referenced by
.Fa *t1
and
.Fa *t2 .
It returns 0 if the two times are equal.
A value of 1 is returned when 
.Fa *t1
is greater than
.Fa *t2 .
If
.Fa *t1
is less than
.Fa *t2
.Fn isc_time_compare
returns -1.
.Pp
The function
.Fn isc_time_add
adds
.Fa *i
to
.Fn *t
and
.Fn *result .
The converse operation is performed by
.Fa isc_time_subtract .
It subtracts
.Fa *i
from
.Fa *t
and stores the result in
.Fa result .
.Pp
.Fn isc_time_microdiff
returns the number of difference in microseconds between
.Fa *t1
and
.Fa *t2.
Zero is returned if the time represented by
.Fa *t1
is less than that given by
.Fa t2 .
.Pp
.Fn isc_time_seconds
and
.Fn isc_time_nanoseconds
return the number of seconds and nanoseconds respectively
in the time indicated by
.Fa *t .
.Pp
The function
.Fn isc_time_secondsastimet
converts the time value represented by
.Fa *t
to the system's
.Nm time_t
struct pointed at by
.Fa *secondsp .
It takes great care to ensure that the number of seconds represented
by
.Nm t->seconds
can be represented by a
.Nm time_t .
This is not as straightforward as it might seem because a
.Nm time_t
might not be an integral type.
Implementations may treat this type as a signed or unsigned quantity
which potentially creates sign extension problems.
.Sh RETURN VALUES
.Fn isc_time_now
and
.Fn isc_time_nowplusinterval
return
.Er ISC_R_UNEXPECTED
if it cannot get the time of day or if the operating system returns
nonsense.
They return
.Er ISC_R_RANGE
if the number of seconds returned by the operating system is too big
to fit in a
.Nm "unsigned int" .
A result of
.Er ISC_R_SUCCESS
is returned on success.
.Pp
Calls to
.Fn isc_time_add ,
.Fn isc_time_subtract 
and
.Fn isc_time_secondsastimet
only return
.Er ISC_R_SUCCESS .
.ft B
So perhaps they should be void functions? - JR
.ft
.Sh SEE ALSO
.Xr gettimeofday 2 ,
.Xr getitimer 2 ,
.Xr ctime 3
.Sh BUGS
Nanosecond- and microsecond resolution time values are notoriously
inaccurate on most
.Ux
systems because few, if any, of them have
hardware which provides that level of precision.
Consult the vendor's documentation.
The resolution of the real-time clock in most systems is typically
100Hz which means the finest granularity of time-related activity is
at most 0.01 seconds.
Scheduling latency can delay the processing of real-time events.
For most DNS activity such as decrementing TTLs or zone refreshes,
this loss of accuracy does not matter.
.Pp
The accuracy of absolute times returned by
.Fn isc_time_now
and
.Fn isc_time_nowplusinterval
depend on the reliability of the system's time of day clock.
This should be synchronised to UTC using an external time source using
a good timekeeping protocol such as NTP.
Pedants might want to worry about whether the absolute time includes
leap seconds or not.