BIND: update vendor tree to 9.5.2-P2
[dragonfly.git] / contrib / bind / lib / isc / unix / include / isc / time.h
1 /*
2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 1998-2001  Internet Software Consortium.
4  *
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.
8  *
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.
16  */
17
18 /* $Id: time.h,v 1.36.128.3 2009/01/06 23:46:48 tbox Exp $ */
19
20 #ifndef ISC_TIME_H
21 #define ISC_TIME_H 1
22
23 /*! \file */
24
25 #include <isc/lang.h>
26 #include <isc/types.h>
27
28 /***
29  *** Intervals
30  ***/
31
32 /*!
33  *  \brief
34  * The contents of this structure are private, and MUST NOT be accessed
35  * directly by callers.
36  *
37  * The contents are exposed only to allow callers to avoid dynamic allocation.
38  */
39 struct isc_interval {
40         unsigned int seconds;
41         unsigned int nanoseconds;
42 };
43
44 extern isc_interval_t *isc_interval_zero;
45
46 ISC_LANG_BEGINDECLS
47
48 void
49 isc_interval_set(isc_interval_t *i,
50                  unsigned int seconds, unsigned int nanoseconds);
51 /*%<
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().
55  *
56  * Requires:
57  *
58  *\li   't' is a valid pointer.
59  *\li   nanoseconds < 1000000000.
60  */
61
62 isc_boolean_t
63 isc_interval_iszero(const isc_interval_t *i);
64 /*%<
65  * Returns ISC_TRUE iff. 'i' is the zero interval.
66  *
67  * Requires:
68  *
69  *\li   'i' is a valid pointer.
70  */
71
72 /***
73  *** Absolute Times
74  ***/
75
76 /*%
77  * The contents of this structure are private, and MUST NOT be accessed
78  * directly by callers.
79  *
80  * The contents are exposed only to allow callers to avoid dynamic allocation.
81  */
82
83 struct isc_time {
84         unsigned int    seconds;
85         unsigned int    nanoseconds;
86 };
87
88 extern isc_time_t *isc_time_epoch;
89
90 void
91 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
92 /*%<
93  * Set 't' to a particular number of seconds + nanoseconds since the epoch.
94  *
95  * Notes:
96  *\li   This call is equivalent to:
97  *\code
98  *      isc_time_settoepoch(t);
99  *      isc_interval_set(i, seconds, nanoseconds);
100  *      isc_time_add(t, i, t);
101  *\endcode
102  * Requires:
103  *\li   't' is a valid pointer.
104  *\li   nanoseconds < 1000000000.
105  */
106
107 void
108 isc_time_settoepoch(isc_time_t *t);
109 /*%<
110  * Set 't' to the time of the epoch.
111  *
112  * Notes:
113  *\li   The date of the epoch is platform-dependent.
114  *
115  * Requires:
116  *
117  *\li   't' is a valid pointer.
118  */
119
120 isc_boolean_t
121 isc_time_isepoch(const isc_time_t *t);
122 /*%<
123  * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
124  *
125  * Requires:
126  *
127  *\li   't' is a valid pointer.
128  */
129
130 isc_result_t
131 isc_time_now(isc_time_t *t);
132 /*%<
133  * Set 't' to the current absolute time.
134  *
135  * Requires:
136  *
137  *\li   't' is a valid pointer.
138  *
139  * Returns:
140  *
141  *\li   Success
142  *\li   Unexpected error
143  *              Getting the time from the system failed.
144  *\li   Out of range
145  *              The time from the system is too large to be represented
146  *              in the current definition of isc_time_t.
147  */
148
149 isc_result_t
150 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);
151 /*%<
152  * Set *t to the current absolute time + i.
153  *
154  * Note:
155  *\li   This call is equivalent to:
156  *
157  *\code
158  *              isc_time_now(t);
159  *              isc_time_add(t, i, t);
160  *\endcode
161  *
162  * Requires:
163  *
164  *\li   't' and 'i' are valid pointers.
165  *
166  * Returns:
167  *
168  *\li   Success
169  *\li   Unexpected error
170  *              Getting the time from the system failed.
171  *\li   Out of range
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.
174  */
175
176 int
177 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);
178 /*%<
179  * Compare the times referenced by 't1' and 't2'
180  *
181  * Requires:
182  *
183  *\li   't1' and 't2' are valid pointers.
184  *
185  * Returns:
186  *
187  *\li   -1              t1 < t2         (comparing times, not pointers)
188  *\li   0               t1 = t2
189  *\li   1               t1 > t2
190  */
191
192 isc_result_t
193 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);
194 /*%<
195  * Add 'i' to 't', storing the result in 'result'.
196  *
197  * Requires:
198  *
199  *\li   't', 'i', and 'result' are valid pointers.
200  *
201  * Returns:
202  *\li   Success
203  *\li   Out of range
204  *              The interval added to the time is too large to
205  *              be represented in the current definition of isc_time_t.
206  */
207
208 isc_result_t
209 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,
210                   isc_time_t *result);
211 /*%<
212  * Subtract 'i' from 't', storing the result in 'result'.
213  *
214  * Requires:
215  *
216  *\li   't', 'i', and 'result' are valid pointers.
217  *
218  * Returns:
219  *\li   Success
220  *\li   Out of range
221  *              The interval is larger than the time since the epoch.
222  */
223
224 isc_uint64_t
225 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);
226 /*%<
227  * Find the difference in microseconds between time t1 and time t2.
228  * t2 is the subtrahend of t1; ie, difference = t1 - t2.
229  *
230  * Requires:
231  *
232  *\li   't1' and 't2' are valid pointers.
233  *
234  * Returns:
235  *\li   The difference of t1 - t2, or 0 if t1 <= t2.
236  */
237
238 isc_uint32_t
239 isc_time_seconds(const isc_time_t *t);
240 /*%<
241  * Return the number of seconds since the epoch stored in a time structure.
242  *
243  * Requires:
244  *
245  *\li   't' is a valid pointer.
246  */
247
248 isc_result_t
249 isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp);
250 /*%<
251  * Ensure the number of seconds in an isc_time_t is representable by a time_t.
252  *
253  * Notes:
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.
262  *
263  * Requires:
264  *\li   't' is a valid pointer.
265  *
266  * Returns:
267  *\li   Success
268  *\li   Out of range
269  */
270
271 isc_uint32_t
272 isc_time_nanoseconds(const isc_time_t *t);
273 /*%<
274  * Return the number of nanoseconds stored in a time structure.
275  *
276  * Notes:
277  *\li   This is the number of nanoseconds in excess of the number
278  *      of seconds since the epoch; it will always be less than one
279  *      full second.
280  *
281  * Requires:
282  *\li   't' is a valid pointer.
283  *
284  * Ensures:
285  *\li   The returned value is less than 1*10^9.
286  */
287
288 void
289 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);
290 /*%<
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.
295  *
296  *  Requires:
297  *\li      'len' > 0
298  *\li      'buf' points to an array of at least len chars
299  *
300  */
301
302 void
303 isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len);
304 /*%<
305  * Format the time 't' into the buffer 'buf' of length 'len',
306  * using a format like "Mon, 30 Aug 2000 04:06:47 GMT"
307  * If the text does not fit in the buffer, the result is indeterminate,
308  * but is always guaranteed to be null terminated.
309  *
310  *  Requires:
311  *\li      'len' > 0
312  *\li      'buf' points to an array of at least len chars
313  *
314  */
315
316 void
317 isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len);
318 /*%<
319  * Format the time 't' into the buffer 'buf' of length 'len',
320  * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ"
321  * If the text does not fit in the buffer, the result is indeterminate,
322  * but is always guaranteed to be null terminated.
323  *
324  *  Requires:
325  *\li      'len' > 0
326  *\li      'buf' points to an array of at least len chars
327  *
328  */
329
330 ISC_LANG_ENDDECLS
331
332 #endif /* ISC_TIME_H */