ComputerSurge/bind9
3
0
Fork 0
Code Pull Requests 1 Activity
Files
4b7c8ee5368285ccdcafe4bbd840e7ba5eb06453
bind9/lib/isc/unix/include/isc/time.h
David Lawrence 6fa1cb5754 189. [func] isc_time_secondsastimet(), a new function, will ensure 
that the number of seconds in an isc_time_t does not
                        exceed the range of a time_t, or return ISC_R_RANGE.
                        Similarly, isc_time_now(), isc_time_nowplusinterval(),
                        isc_time_add() and isc_time_subtract() now check the
                        range for overflow/underflow.  In the case of
                        isc_time_subtract, this changed a calling requirement
                        (ie, something that could generate an assertion)
                        into merely a condition that returns an error result.
                        isc_time_add() and isc_time_subtract() were void-
                        valued before but now return isc_result_t.

The seconds member isc_time_t on Unix platforms was changed from time_t
to unsigned int.

unix/time.c now uses macros for nanoseconds per second, nanoseconds per
microsecond and microseconds per second to make sure that the right
number of zeros appears each place the constant is used.

unix/time.c functions which take initialized isc_(interval|time)_t arguments
INSIST() that the nanoseconds value is less than one full second.

unix/time.c's isc_time_microdiff was broken because it did multiplication and
addition with unsigned integers and attempted to set them a 64 bit int to
avoid overflow, but C's ints don't promote to 64 bits on machines that only
have 32 bit longs.  Fixed.

Added all the pertinent documentation to time.h.
2000-05-18 17:08:32 +00:00

280 lines
6.1 KiB
C
Raw Blame History

/*
* Copyright (C) 1998, 1999, 2000 Internet Software Consortium.
*
* Permission to use, copy, modify, and distribute this software 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.
*/
#ifndef ISC_TIME_H
#define ISC_TIME_H 1
#include <isc/lang.h>
#include <isc/types.h>
/***
*** Intervals
***/
/*
* The contents of this structure are private, and MUST NOT be accessed
* directly by callers.
*
* The contents are exposed only to allow callers to avoid dynamic allocation.
*/
struct isc_interval {
unsigned int seconds;
unsigned int nanoseconds;
};
extern isc_interval_t *isc_interval_zero;
ISC_LANG_BEGINDECLS
void
isc_interval_set(isc_interval_t *i,
unsigned int seconds, unsigned int nanoseconds);
/*
* Set 'i' to a value representing an interval of 'seconds' seconds and
* 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
* isc_time_subtract().
*
* Requires:
*
* 't' is a valid pointer.
* nanoseconds < 1000000000.
*/
isc_boolean_t
isc_interval_iszero(isc_interval_t *i);
/*
* Returns ISC_TRUE iff. 'i' is the zero interval.
*
* Requires:
*
* 'i' is a valid pointer.
*/
/***
*** Absolute Times
***/
/*
* The contents of this structure are private, and MUST NOT be accessed
* directly by callers.
*
* The contents are exposed only to allow callers to avoid dynamic allocation.
*/
struct isc_time {
unsigned int seconds;
unsigned int nanoseconds;
};
extern isc_time_t *isc_time_epoch;
void
isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
/*
* Set 't' to a particular number of seconds + nanoseconds since the epoch.
*
* Notes:
* This call is equivalent to:
*
* isc_time_settoepoch(t);
* isc_interval_set(i, seconds, nanoseconds);
* isc_time_add(t, i, t);
*
* Requires:
* 't' is a valid pointer.
* nanoseconds < 1000000000.
*/
void
isc_time_settoepoch(isc_time_t *t);
/*
* Set 't' to the time of the epoch.
*
* Notes:
* The date of the epoch is platform-dependent.
*
* Requires:
*
* 't' is a valid pointer.
*/
isc_boolean_t
isc_time_isepoch(isc_time_t *t);
/*
* Returns ISC_TRUE iff. 't' is the epoch ("time zero").
*
* Requires:
*
* 't' is a valid pointer.
*/
isc_result_t
isc_time_now(isc_time_t *t);
/*
* Set 't' to the current absolute time.
*
* Requires:
*
* 't' is a valid pointer.
*
* Returns:
*
* Success
* Unexpected error
* Getting the time from the system failed.
* Out of range
* The time from the system is too large to be represented
* in the current definition of isc_time_t.
*/
isc_result_t
isc_time_nowplusinterval(isc_time_t *t, isc_interval_t *i);
/*
* Set *t to the current absolute time + i.
*
* Note:
* This call is equivalent to:
*
* isc_time_now(t);
* isc_time_add(t, i, t);
*
* Requires:
*
* 't' and 'i' are valid pointers.
*
* Returns:
*
* Success
* Unexpected error
* Getting the time from the system failed.
* Out of range
* The interval added to the time from the system is too large to
* be represented in the current definition of isc_time_t.
*/
int
isc_time_compare(isc_time_t *t1, isc_time_t *t2);
/*
* Compare the times referenced by 't1' and 't2'
*
* Requires:
*
* 't1' and 't2' are valid pointers.
*
* Returns:
*
* -1 t1 < t2 (comparing times, not pointers)
* 0 t1 = t2
* 1 t1 > t2
*/
isc_result_t
isc_time_add(isc_time_t *t, isc_interval_t *i, isc_time_t *result);
/*
* Add 'i' to 't', storing the result in 'result'.
*
* Requires:
*
* 't', 'i', and 'result' are valid pointers.
*
* Returns:
* Success
* Out of range
* The interval added to the time is too large to
* be represented in the current definition of isc_time_t.
*/
isc_result_t
isc_time_subtract(isc_time_t *t, isc_interval_t *i, isc_time_t *result);
/*
* Subtract 'i' from 't', storing the result in 'result'.
*
* Requires:
*
* 't', 'i', and 'result' are valid pointers.
*
* Returns:
* Success
* Out of range
* The interval is larger than the time since the epoch.
*/
isc_uint64_t
isc_time_microdiff(isc_time_t *t1, isc_time_t *t2);
/*
* Find the difference in milliseconds between time t1 and time t2.
* t2 is the subtrahend of t1; ie, difference = t1 - t2.
*
* Requires:
*
* 't1' and 't2' are valid pointers.
*/
isc_uint32_t
isc_time_seconds(isc_time_t *t);
/*
* Return the number of seconds since the epoch stored in a time structure.
*
* Requires:
*
* 't' is a valid pointer.
*/
isc_result_t
isc_time_secondsastimet(isc_time_t *t, time_t *secondsp);
/*
* Ensure the number of seconds in an isc_time_t is representable by a time_t.
*
* Notes:
* The number of seconds stored in an isc_time_t might be larger
* than the number of seconds a time_t is able to handle. Since
* time_t is mostly opaque according to the ANSI/ISO standard
* (essentially, all you can be sure of is that it is an arithmetic type,
* not even necessarily integral), it can be tricky to ensure that
* the isc_time_t is in the range a time_t can handle. Use this
* function in place of isc_time_seconds() any time you need to set a
* time_t from an isc_time_t.
*
* Requires:
* 't' is a valid pointer.
*
* Returns:
* Success
* Out of range
*/
isc_uint32_t
isc_time_nanoseconds(isc_time_t *t);
/*
* Return the number of nanoseconds stored in a time structure.
*
* Notes:
* This is the number of nanoseconds in excess of the the number
* of seconds since the epoch; it will always be less than one
* full second.
*
* Requires:
* 't' is a valid pointer.
*
* Ensures:
* The returned value is less than 1*10^9.
*/
ISC_LANG_ENDDECLS
#endif /* ISC_TIME_H */
View Git Blame Copy Permalink