2 * Copyright (C) 2004, 2005 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: time.h,v 1.30.18.2 2005/04/29 00:17:10 marka Exp $ */
26 #include <isc/types.h>
34 * The contents of this structure are private, and MUST NOT be accessed
35 * directly by callers.
37 * The contents are exposed only to allow callers to avoid dynamic allocation.
41 unsigned int nanoseconds;
44 extern isc_interval_t *isc_interval_zero;
49 isc_interval_set(isc_interval_t *i,
50 unsigned int seconds, unsigned int nanoseconds);
52 * Set 'i' to a value representing an interval of 'seconds' seconds and
53 * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
54 * isc_time_subtract().
58 *\li 't' is a valid pointer.
59 *\li nanoseconds < 1000000000.
63 isc_interval_iszero(const isc_interval_t *i);
65 * Returns ISC_TRUE iff. 'i' is the zero interval.
69 *\li 'i' is a valid pointer.
77 * The contents of this structure are private, and MUST NOT be accessed
78 * directly by callers.
80 * The contents are exposed only to allow callers to avoid dynamic allocation.
85 unsigned int nanoseconds;
88 extern isc_time_t *isc_time_epoch;
91 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
93 * Set 't' to a particular number of seconds + nanoseconds since the epoch.
96 *\li This call is equivalent to:
98 * isc_time_settoepoch(t);
99 * isc_interval_set(i, seconds, nanoseconds);
100 * isc_time_add(t, i, t);
103 *\li 't' is a valid pointer.
104 *\li nanoseconds < 1000000000.
108 isc_time_settoepoch(isc_time_t *t);
110 * Set 't' to the time of the epoch.
113 * \li The date of the epoch is platform-dependent.
117 *\li 't' is a valid pointer.
121 isc_time_isepoch(const isc_time_t *t);
123 * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
127 *\li 't' is a valid pointer.
131 isc_time_now(isc_time_t *t);
133 * Set 't' to the current absolute time.
137 *\li 't' is a valid pointer.
142 *\li Unexpected error
143 * Getting the time from the system failed.
145 * The time from the system is too large to be represented
146 * in the current definition of isc_time_t.
150 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);
152 * Set *t to the current absolute time + i.
155 *\li This call is equivalent to:
159 * isc_time_add(t, i, t);
164 *\li 't' and 'i' are valid pointers.
169 *\li Unexpected error
170 * Getting the time from the system failed.
172 * The interval added to the time from the system is too large to
173 * be represented in the current definition of isc_time_t.
177 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);
179 * Compare the times referenced by 't1' and 't2'
183 *\li 't1' and 't2' are valid pointers.
187 *\li -1 t1 < t2 (comparing times, not pointers)
193 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);
195 * Add 'i' to 't', storing the result in 'result'.
199 *\li 't', 'i', and 'result' are valid pointers.
204 * The interval added to the time is too large to
205 * be represented in the current definition of isc_time_t.
209 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,
212 * Subtract 'i' from 't', storing the result in 'result'.
216 *\li 't', 'i', and 'result' are valid pointers.
221 * The interval is larger than the time since the epoch.
225 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);
227 * Find the difference in microseconds between time t1 and time t2.
228 * t2 is the subtrahend of t1; ie, difference = t1 - t2.
232 *\li 't1' and 't2' are valid pointers.
235 *\li The difference of t1 - t2, or 0 if t1 <= t2.
239 isc_time_seconds(const isc_time_t *t);
241 * Return the number of seconds since the epoch stored in a time structure.
245 *\li 't' is a valid pointer.
249 isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp);
251 * Ensure the number of seconds in an isc_time_t is representable by a time_t.
254 *\li The number of seconds stored in an isc_time_t might be larger
255 * than the number of seconds a time_t is able to handle. Since
256 * time_t is mostly opaque according to the ANSI/ISO standard
257 * (essentially, all you can be sure of is that it is an arithmetic type,
258 * not even necessarily integral), it can be tricky to ensure that
259 * the isc_time_t is in the range a time_t can handle. Use this
260 * function in place of isc_time_seconds() any time you need to set a
261 * time_t from an isc_time_t.
264 *\li 't' is a valid pointer.
272 isc_time_nanoseconds(const isc_time_t *t);
274 * Return the number of nanoseconds stored in a time structure.
277 *\li This is the number of nanoseconds in excess of the the number
278 * of seconds since the epoch; it will always be less than one
282 *\li 't' is a valid pointer.
285 *\li The returned value is less than 1*10^9.
289 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);
291 * Format the time 't' into the buffer 'buf' of length 'len',
292 * using a format like "30-Aug-2000 04:06:47.997" and the local time zone.
293 * If the text does not fit in the buffer, the result is indeterminate,
294 * but is always guaranteed to be null terminated.
298 * \li 'buf' points to an array of at least len chars
304 #endif /* ISC_TIME_H */