2 * Copyright (C) 2004, 2006-2009 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2001 Internet Software Consortium.
5 * Permission to use, copy, modify, and/or 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.35 2009/01/05 23:47:54 tbox Exp $ */
26 #include <isc/types.h>
33 * The contents of this structure are private, and MUST NOT be accessed
34 * directly by callers.
36 * The contents are exposed only to allow callers to avoid dynamic allocation.
42 LIBISC_EXTERNAL_DATA extern isc_interval_t *isc_interval_zero;
47 isc_interval_set(isc_interval_t *i,
48 unsigned int seconds, unsigned int nanoseconds);
50 * Set 'i' to a value representing an interval of 'seconds' seconds and
51 * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
52 * isc_time_subtract().
56 * 't' is a valid pointer.
57 * nanoseconds < 1000000000.
61 isc_interval_iszero(const isc_interval_t *i);
63 * Returns ISC_TRUE iff. 'i' is the zero interval.
67 * 'i' is a valid pointer.
75 * The contents of this structure are private, and MUST NOT be accessed
76 * directly by callers.
78 * The contents are exposed only to allow callers to avoid dynamic allocation.
85 LIBISC_EXTERNAL_DATA extern isc_time_t *isc_time_epoch;
88 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
90 * Set 't' to a value which represents the given number of seconds and
91 * nanoseconds since 00:00:00 January 1, 1970, UTC.
94 *\li 't' is a valid pointer.
95 *\li nanoseconds < 1000000000.
99 isc_time_settoepoch(isc_time_t *t);
101 * Set 't' to the time of the epoch.
104 * The date of the epoch is platform-dependent.
108 * 't' is a valid pointer.
112 isc_time_isepoch(const isc_time_t *t);
114 * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
118 * 't' is a valid pointer.
122 isc_time_now(isc_time_t *t);
124 * Set 't' to the current absolute time.
128 * 't' is a valid pointer.
134 * Getting the time from the system failed.
136 * The time from the system is too large to be represented
137 * in the current definition of isc_time_t.
141 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);
143 * Set *t to the current absolute time + i.
146 * This call is equivalent to:
149 * isc_time_add(t, i, t);
153 * 't' and 'i' are valid pointers.
159 * Getting the time from the system failed.
161 * The interval added to the time from the system is too large to
162 * be represented in the current definition of isc_time_t.
166 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);
168 * Compare the times referenced by 't1' and 't2'
172 * 't1' and 't2' are valid pointers.
176 * -1 t1 < t2 (comparing times, not pointers)
182 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);
184 * Add 'i' to 't', storing the result in 'result'.
188 * 't', 'i', and 'result' are valid pointers.
193 * The interval added to the time is too large to
194 * be represented in the current definition of isc_time_t.
198 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,
201 * Subtract 'i' from 't', storing the result in 'result'.
205 * 't', 'i', and 'result' are valid pointers.
210 * The interval is larger than the time since the epoch.
214 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);
216 * Find the difference in milliseconds between time t1 and time t2.
217 * t2 is the subtrahend of t1; ie, difference = t1 - t2.
221 * 't1' and 't2' are valid pointers.
224 * The difference of t1 - t2, or 0 if t1 <= t2.
228 isc_time_nanoseconds(const isc_time_t *t);
230 * Return the number of nanoseconds stored in a time structure.
233 * This is the number of nanoseconds in excess of the number
234 * of seconds since the epoch; it will always be less than one
238 * 't' is a valid pointer.
241 * The returned value is less than 1*10^9.
245 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);
247 * Format the time 't' into the buffer 'buf' of length 'len',
248 * using a format like "30-Aug-2000 04:06:47.997" and the local time zone.
249 * If the text does not fit in the buffer, the result is indeterminate,
250 * but is always guaranteed to be null terminated.
254 * 'buf' points to an array of at least len chars
259 isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len);
261 * Format the time 't' into the buffer 'buf' of length 'len',
262 * using a format like "Mon, 30 Aug 2000 04:06:47 GMT"
263 * If the text does not fit in the buffer, the result is indeterminate,
264 * but is always guaranteed to be null terminated.
268 * 'buf' points to an array of at least len chars
273 isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len);
275 * Format the time 't' into the buffer 'buf' of length 'len',
276 * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ"
277 * If the text does not fit in the buffer, the result is indeterminate,
278 * but is always guaranteed to be null terminated.
282 *\li 'buf' points to an array of at least len chars
287 isc_time_seconds(const isc_time_t *t);
291 #endif /* ISC_TIME_H */