time.h revision 15a44745412679c30a6d022733925af70a38b715
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews/*
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Copyright (C) 1998-2000 Internet Software Consortium.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Permission to use, copy, modify, and distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User * purpose with or without fee is hereby granted, provided that the above
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User * copyright notice and this permission notice appear in all copies.
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews * DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt */
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/* $Id: time.h,v 1.23 2000/07/27 09:53:08 tale Exp $ */
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews#ifndef ISC_TIME_H
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews#define ISC_TIME_H 1
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews#include <isc/lang.h>
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews#include <isc/types.h>
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/***
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *** Intervals
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews ***/
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/*
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * The contents of this structure are private, and MUST NOT be accessed
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * directly by callers.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * The contents are exposed only to allow callers to avoid dynamic allocation.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User */
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsstruct isc_interval {
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User unsigned int seconds;
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews unsigned int nanoseconds;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User};
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox Userextern isc_interval_t *isc_interval_zero;
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox UserISC_LANG_BEGINDECLS
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Uservoid
7e71f05d8643aca84914437c900cb716444507e4Tinderbox Userisc_interval_set(isc_interval_t *i,
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User unsigned int seconds, unsigned int nanoseconds);
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater/*
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt * Set 'i' to a value representing an interval of 'seconds' seconds and
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater * isc_time_subtract().
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater *
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater * Requires:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User *
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt * 't' is a valid pointer.
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater * nanoseconds < 1000000000.
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater */
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntisc_boolean_t
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Huntisc_interval_iszero(isc_interval_t *i);
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt/*
d856585f5fe37cc2ea82115c10339578d2b517b1Automatic Updater * Returns ISC_TRUE iff. 'i' is the zero interval.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Requires:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User *
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User * 'i' is a valid pointer.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User */
f7b41fd9291b8f4dba27e2b57e1d93f0913a4f1dMark Andrews
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User/***
f7b41fd9291b8f4dba27e2b57e1d93f0913a4f1dMark Andrews *** Absolute Times
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User ***/
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User/*
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User * The contents of this structure are private, and MUST NOT be accessed
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User * directly by callers.
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User *
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User * The contents are exposed only to allow callers to avoid dynamic allocation.
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User */
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox Userstruct isc_time {
ea640e04eae220b5e569f188563eb1f204c7c77eTinderbox User unsigned int seconds;
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews unsigned int nanoseconds;
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User};
d85c83c4144116fbc2734a6a623a888fea1a307fAutomatic Updater
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsextern isc_time_t *isc_time_epoch;
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Uservoid
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsisc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User/*
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt * Set 't' to a particular number of seconds + nanoseconds since the epoch.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Notes:
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * This call is equivalent to:
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User *
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * isc_time_settoepoch(t);
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * isc_interval_set(i, seconds, nanoseconds);
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * isc_time_add(t, i, t);
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User *
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * Requires:
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * 't' is a valid pointer.
990d0e893f5b70e735cdf990af66e9ec6e91fa78Tinderbox User * nanoseconds < 1000000000.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User */
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Uservoid
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrewsisc_time_settoepoch(isc_time_t *t);
d71e2e0c61df16ff37c9934c371a4a60c08974f7Mark Andrews/*
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Set 't' to the time of the epoch.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Notes:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * The date of the epoch is platform-dependent.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Requires:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * 't' is a valid pointer.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User */
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userisc_boolean_t
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsisc_time_isepoch(isc_time_t *t);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/*
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * Requires:
7e71f05d8643aca84914437c900cb716444507e4Tinderbox User *
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User * 't' is a valid pointer.
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox User */
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsisc_result_t
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userisc_time_now(isc_time_t *t);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/*
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Set 't' to the current absolute time.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Requires:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * 't' is a valid pointer.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt *
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User * Returns:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Success
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Unexpected error
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * Getting the time from the system failed.
4abdfc917e6635a7c81d1f931a0c79227e72d025Mark Andrews * Out of range
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt * The time from the system is too large to be represented
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * in the current definition of isc_time_t.
4abdfc917e6635a7c81d1f931a0c79227e72d025Mark Andrews */
4abdfc917e6635a7c81d1f931a0c79227e72d025Mark Andrews
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsisc_result_t
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsisc_time_nowplusinterval(isc_time_t *t, isc_interval_t *i);
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews/*
1ca759b3f5c0672b2a66bc02288fe010cabbfe37Tinderbox User * Set *t to the current absolute time + i.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews *
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews * 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 microseconds between time t1 and time t2.
* t2 is the subtrahend of t1; ie, difference = t1 - t2.
*
* Requires:
*
* 't1' and 't2' are valid pointers.
*
* Returns:
* The difference of t1 - t2, or 0 if t1 <= t2.
*/
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 */