1 /* $NetBSD: time.h,v 1.1.1.1 2009/12/13 16:54:47 kardel Exp $ */ 2 3 /* 4 * Copyright (C) 2004, 2006-2009 Internet Systems Consortium, Inc. ("ISC") 5 * Copyright (C) 1998-2001 Internet Software Consortium. 6 * 7 * Permission to use, copy, modify, and/or distribute this software for any 8 * purpose with or without fee is hereby granted, provided that the above 9 * copyright notice and this permission notice appear in all copies. 10 * 11 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 12 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 13 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 14 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 16 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 17 * PERFORMANCE OF THIS SOFTWARE. 18 */ 19 20 /* Id: time.h,v 1.33.56.2 2009/01/05 23:47:23 tbox Exp */ 21 22 #ifndef ISC_TIME_H 23 #define ISC_TIME_H 1 24 25 #include <windows.h> 26 27 #include <isc/lang.h> 28 #include <isc/types.h> 29 30 /*** 31 *** Intervals 32 ***/ 33 34 /* 35 * The contents of this structure are private, and MUST NOT be accessed 36 * directly by callers. 37 * 38 * The contents are exposed only to allow callers to avoid dynamic allocation. 39 */ 40 struct isc_interval { 41 isc_int64_t interval; 42 }; 43 44 LIBISC_EXTERNAL_DATA 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 * 't' is a valid pointer. 59 * 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 * '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 FILETIME absolute; 85 }; 86 87 LIBISC_EXTERNAL_DATA extern isc_time_t *isc_time_epoch; 88 89 void 90 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds); 91 /*%< 92 * Set 't' to a value which represents the given number of seconds and 93 * nanoseconds since 00:00:00 January 1, 1970, UTC. 94 * 95 * Requires: 96 *\li 't' is a valid pointer. 97 *\li nanoseconds < 1000000000. 98 */ 99 100 void 101 isc_time_settoepoch(isc_time_t *t); 102 /* 103 * Set 't' to the time of the epoch. 104 * 105 * Notes: 106 * The date of the epoch is platform-dependent. 107 * 108 * Requires: 109 * 110 * 't' is a valid pointer. 111 */ 112 113 isc_boolean_t 114 isc_time_isepoch(const isc_time_t *t); 115 /* 116 * Returns ISC_TRUE iff. 't' is the epoch ("time zero"). 117 * 118 * Requires: 119 * 120 * 't' is a valid pointer. 121 */ 122 123 isc_result_t 124 isc_time_now(isc_time_t *t); 125 /* 126 * Set 't' to the current absolute time. 127 * 128 * Requires: 129 * 130 * 't' is a valid pointer. 131 * 132 * Returns: 133 * 134 * Success 135 * Unexpected error 136 * Getting the time from the system failed. 137 * Out of range 138 * The time from the system is too large to be represented 139 * in the current definition of isc_time_t. 140 */ 141 142 isc_result_t 143 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i); 144 /* 145 * Set *t to the current absolute time + i. 146 * 147 * Note: 148 * This call is equivalent to: 149 * 150 * isc_time_now(t); 151 * isc_time_add(t, i, t); 152 * 153 * Requires: 154 * 155 * 't' and 'i' are valid pointers. 156 * 157 * Returns: 158 * 159 * Success 160 * Unexpected error 161 * Getting the time from the system failed. 162 * Out of range 163 * The interval added to the time from the system is too large to 164 * be represented in the current definition of isc_time_t. 165 */ 166 167 int 168 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2); 169 /* 170 * Compare the times referenced by 't1' and 't2' 171 * 172 * Requires: 173 * 174 * 't1' and 't2' are valid pointers. 175 * 176 * Returns: 177 * 178 * -1 t1 < t2 (comparing times, not pointers) 179 * 0 t1 = t2 180 * 1 t1 > t2 181 */ 182 183 isc_result_t 184 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); 185 /* 186 * Add 'i' to 't', storing the result in 'result'. 187 * 188 * Requires: 189 * 190 * 't', 'i', and 'result' are valid pointers. 191 * 192 * Returns: 193 * Success 194 * Out of range 195 * The interval added to the time is too large to 196 * be represented in the current definition of isc_time_t. 197 */ 198 199 isc_result_t 200 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i, 201 isc_time_t *result); 202 /* 203 * Subtract 'i' from 't', storing the result in 'result'. 204 * 205 * Requires: 206 * 207 * 't', 'i', and 'result' are valid pointers. 208 * 209 * Returns: 210 * Success 211 * Out of range 212 * The interval is larger than the time since the epoch. 213 */ 214 215 isc_uint64_t 216 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2); 217 /* 218 * Find the difference in milliseconds between time t1 and time t2. 219 * t2 is the subtrahend of t1; ie, difference = t1 - t2. 220 * 221 * Requires: 222 * 223 * 't1' and 't2' are valid pointers. 224 * 225 * Returns: 226 * The difference of t1 - t2, or 0 if t1 <= t2. 227 */ 228 229 isc_uint32_t 230 isc_time_nanoseconds(const isc_time_t *t); 231 /* 232 * Return the number of nanoseconds stored in a time structure. 233 * 234 * Notes: 235 * This is the number of nanoseconds in excess of the number 236 * of seconds since the epoch; it will always be less than one 237 * full second. 238 * 239 * Requires: 240 * 't' is a valid pointer. 241 * 242 * Ensures: 243 * The returned value is less than 1*10^9. 244 */ 245 246 void 247 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len); 248 /* 249 * Format the time 't' into the buffer 'buf' of length 'len', 250 * using a format like "30-Aug-2000 04:06:47.997" and the local time zone. 251 * If the text does not fit in the buffer, the result is indeterminate, 252 * but is always guaranteed to be null terminated. 253 * 254 * Requires: 255 * 'len' > 0 256 * 'buf' points to an array of at least len chars 257 * 258 */ 259 260 void 261 isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len); 262 /* 263 * Format the time 't' into the buffer 'buf' of length 'len', 264 * using a format like "Mon, 30 Aug 2000 04:06:47 GMT" 265 * If the text does not fit in the buffer, the result is indeterminate, 266 * but is always guaranteed to be null terminated. 267 * 268 * Requires: 269 * 'len' > 0 270 * 'buf' points to an array of at least len chars 271 * 272 */ 273 274 void 275 isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len); 276 /*%< 277 * Format the time 't' into the buffer 'buf' of length 'len', 278 * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ" 279 * If the text does not fit in the buffer, the result is indeterminate, 280 * but is always guaranteed to be null terminated. 281 * 282 * Requires: 283 *\li 'len' > 0 284 *\li 'buf' points to an array of at least len chars 285 * 286 */ 287 288 isc_uint32_t 289 isc_time_seconds(const isc_time_t *t); 290 291 ISC_LANG_ENDDECLS 292 293 #endif /* ISC_TIME_H */ 294