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