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