1290001Sglebius/* 2290001Sglebius * Copyright (C) 2004-2009 Internet Systems Consortium, Inc. ("ISC") 3290001Sglebius * Copyright (C) 1998-2001 Internet Software Consortium. 4290001Sglebius * 5290001Sglebius * Permission to use, copy, modify, and/or distribute this software for any 6290001Sglebius * purpose with or without fee is hereby granted, provided that the above 7290001Sglebius * copyright notice and this permission notice appear in all copies. 8290001Sglebius * 9290001Sglebius * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10290001Sglebius * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11290001Sglebius * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12290001Sglebius * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13290001Sglebius * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14290001Sglebius * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15290001Sglebius * PERFORMANCE OF THIS SOFTWARE. 16290001Sglebius */ 17290001Sglebius 18290001Sglebius/* $Id: time.h,v 1.40 2009/01/05 23:47:54 tbox Exp $ */ 19290001Sglebius 20290001Sglebius#ifndef ISC_TIME_H 21290001Sglebius#define ISC_TIME_H 1 22290001Sglebius 23290001Sglebius/*! \file */ 24290001Sglebius 25290001Sglebius#include <isc/lang.h> 26290001Sglebius#include <isc/types.h> 27290001Sglebius 28290001Sglebius/*** 29290001Sglebius *** Intervals 30290001Sglebius ***/ 31290001Sglebius 32290001Sglebius/*! 33290001Sglebius * \brief 34290001Sglebius * The contents of this structure are private, and MUST NOT be accessed 35290001Sglebius * directly by callers. 36290001Sglebius * 37290001Sglebius * The contents are exposed only to allow callers to avoid dynamic allocation. 38290001Sglebius */ 39290001Sglebiusstruct isc_interval { 40290001Sglebius unsigned int seconds; 41290001Sglebius unsigned int nanoseconds; 42290001Sglebius}; 43290001Sglebius 44290001Sglebiusextern isc_interval_t *isc_interval_zero; 45290001Sglebius 46290001SglebiusISC_LANG_BEGINDECLS 47290001Sglebius 48290001Sglebiusvoid 49290001Sglebiusisc_interval_set(isc_interval_t *i, 50290001Sglebius unsigned int seconds, unsigned int nanoseconds); 51290001Sglebius/*%< 52290001Sglebius * Set 'i' to a value representing an interval of 'seconds' seconds and 53290001Sglebius * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and 54290001Sglebius * isc_time_subtract(). 55290001Sglebius * 56290001Sglebius * Requires: 57290001Sglebius * 58290001Sglebius *\li 't' is a valid pointer. 59290001Sglebius *\li nanoseconds < 1000000000. 60290001Sglebius */ 61290001Sglebius 62290001Sglebiusisc_boolean_t 63290001Sglebiusisc_interval_iszero(const isc_interval_t *i); 64290001Sglebius/*%< 65290001Sglebius * Returns ISC_TRUE iff. 'i' is the zero interval. 66290001Sglebius * 67290001Sglebius * Requires: 68290001Sglebius * 69290001Sglebius *\li 'i' is a valid pointer. 70290001Sglebius */ 71290001Sglebius 72290001Sglebius/*** 73290001Sglebius *** Absolute Times 74290001Sglebius ***/ 75290001Sglebius 76290001Sglebius/*% 77290001Sglebius * The contents of this structure are private, and MUST NOT be accessed 78290001Sglebius * directly by callers. 79290001Sglebius * 80290001Sglebius * The contents are exposed only to allow callers to avoid dynamic allocation. 81290001Sglebius */ 82290001Sglebius 83290001Sglebiusstruct isc_time { 84290001Sglebius unsigned int seconds; 85290001Sglebius unsigned int nanoseconds; 86290001Sglebius}; 87290001Sglebius 88290001Sglebiusextern isc_time_t *isc_time_epoch; 89290001Sglebius 90290001Sglebiusvoid 91290001Sglebiusisc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds); 92290001Sglebius/*%< 93290001Sglebius * Set 't' to a value which represents the given number of seconds and 94290001Sglebius * nanoseconds since 00:00:00 January 1, 1970, UTC. 95290001Sglebius * 96290001Sglebius * Notes: 97290001Sglebius *\li The Unix version of this call is equivalent to: 98290001Sglebius *\code 99290001Sglebius * isc_time_settoepoch(t); 100290001Sglebius * isc_interval_set(i, seconds, nanoseconds); 101290001Sglebius * isc_time_add(t, i, t); 102290001Sglebius *\endcode 103290001Sglebius * 104290001Sglebius * Requires: 105290001Sglebius *\li 't' is a valid pointer. 106290001Sglebius *\li nanoseconds < 1000000000. 107290001Sglebius */ 108290001Sglebius 109290001Sglebiusvoid 110290001Sglebiusisc_time_settoepoch(isc_time_t *t); 111290001Sglebius/*%< 112290001Sglebius * Set 't' to the time of the epoch. 113290001Sglebius * 114290001Sglebius * Notes: 115290001Sglebius *\li The date of the epoch is platform-dependent. 116290001Sglebius * 117290001Sglebius * Requires: 118290001Sglebius * 119290001Sglebius *\li 't' is a valid pointer. 120290001Sglebius */ 121290001Sglebius 122290001Sglebiusisc_boolean_t 123290001Sglebiusisc_time_isepoch(const isc_time_t *t); 124290001Sglebius/*%< 125290001Sglebius * Returns ISC_TRUE iff. 't' is the epoch ("time zero"). 126290001Sglebius * 127290001Sglebius * Requires: 128290001Sglebius * 129290001Sglebius *\li 't' is a valid pointer. 130290001Sglebius */ 131290001Sglebius 132290001Sglebiusisc_result_t 133290001Sglebiusisc_time_now(isc_time_t *t); 134290001Sglebius/*%< 135290001Sglebius * Set 't' to the current absolute time. 136290001Sglebius * 137290001Sglebius * Requires: 138290001Sglebius * 139290001Sglebius *\li 't' is a valid pointer. 140290001Sglebius * 141290001Sglebius * Returns: 142290001Sglebius * 143290001Sglebius *\li Success 144290001Sglebius *\li Unexpected error 145290001Sglebius * Getting the time from the system failed. 146290001Sglebius *\li Out of range 147290001Sglebius * The time from the system is too large to be represented 148290001Sglebius * in the current definition of isc_time_t. 149290001Sglebius */ 150290001Sglebius 151290001Sglebiusisc_result_t 152290001Sglebiusisc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i); 153290001Sglebius/*%< 154290001Sglebius * Set *t to the current absolute time + i. 155290001Sglebius * 156290001Sglebius * Note: 157290001Sglebius *\li This call is equivalent to: 158290001Sglebius * 159290001Sglebius *\code 160290001Sglebius * isc_time_now(t); 161290001Sglebius * isc_time_add(t, i, t); 162290001Sglebius *\endcode 163290001Sglebius * 164290001Sglebius * Requires: 165290001Sglebius * 166290001Sglebius *\li 't' and 'i' are valid pointers. 167290001Sglebius * 168290001Sglebius * Returns: 169290001Sglebius * 170290001Sglebius *\li Success 171290001Sglebius *\li Unexpected error 172290001Sglebius * Getting the time from the system failed. 173290001Sglebius *\li Out of range 174290001Sglebius * The interval added to the time from the system is too large to 175290001Sglebius * be represented in the current definition of isc_time_t. 176290001Sglebius */ 177290001Sglebius 178290001Sglebiusint 179290001Sglebiusisc_time_compare(const isc_time_t *t1, const isc_time_t *t2); 180290001Sglebius/*%< 181290001Sglebius * Compare the times referenced by 't1' and 't2' 182290001Sglebius * 183290001Sglebius * Requires: 184290001Sglebius * 185290001Sglebius *\li 't1' and 't2' are valid pointers. 186290001Sglebius * 187290001Sglebius * Returns: 188290001Sglebius * 189290001Sglebius *\li -1 t1 < t2 (comparing times, not pointers) 190290001Sglebius *\li 0 t1 = t2 191290001Sglebius *\li 1 t1 > t2 192290001Sglebius */ 193290001Sglebius 194290001Sglebiusisc_result_t 195290001Sglebiusisc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); 196290001Sglebius/*%< 197290001Sglebius * Add 'i' to 't', storing the result in 'result'. 198290001Sglebius * 199290001Sglebius * Requires: 200290001Sglebius * 201290001Sglebius *\li 't', 'i', and 'result' are valid pointers. 202290001Sglebius * 203290001Sglebius * Returns: 204290001Sglebius *\li Success 205290001Sglebius *\li Out of range 206290001Sglebius * The interval added to the time is too large to 207290001Sglebius * be represented in the current definition of isc_time_t. 208290001Sglebius */ 209290001Sglebius 210290001Sglebiusisc_result_t 211290001Sglebiusisc_time_subtract(const isc_time_t *t, const isc_interval_t *i, 212290001Sglebius isc_time_t *result); 213290001Sglebius/*%< 214290001Sglebius * Subtract 'i' from 't', storing the result in 'result'. 215290001Sglebius * 216290001Sglebius * Requires: 217290001Sglebius * 218290001Sglebius *\li 't', 'i', and 'result' are valid pointers. 219290001Sglebius * 220290001Sglebius * Returns: 221290001Sglebius *\li Success 222290001Sglebius *\li Out of range 223290001Sglebius * The interval is larger than the time since the epoch. 224290001Sglebius */ 225290001Sglebius 226290001Sglebiusisc_uint64_t 227290001Sglebiusisc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2); 228290001Sglebius/*%< 229290001Sglebius * Find the difference in microseconds between time t1 and time t2. 230290001Sglebius * t2 is the subtrahend of t1; ie, difference = t1 - t2. 231290001Sglebius * 232290001Sglebius * Requires: 233290001Sglebius * 234290001Sglebius *\li 't1' and 't2' are valid pointers. 235290001Sglebius * 236290001Sglebius * Returns: 237290001Sglebius *\li The difference of t1 - t2, or 0 if t1 <= t2. 238290001Sglebius */ 239290001Sglebius 240290001Sglebiusisc_uint32_t 241290001Sglebiusisc_time_seconds(const isc_time_t *t); 242290001Sglebius/*%< 243290001Sglebius * Return the number of seconds since the epoch stored in a time structure. 244290001Sglebius * 245290001Sglebius * Requires: 246290001Sglebius * 247290001Sglebius *\li 't' is a valid pointer. 248290001Sglebius */ 249290001Sglebius 250290001Sglebiusisc_result_t 251290001Sglebiusisc_time_secondsastimet(const isc_time_t *t, time_t *secondsp); 252290001Sglebius/*%< 253290001Sglebius * Ensure the number of seconds in an isc_time_t is representable by a time_t. 254290001Sglebius * 255290001Sglebius * Notes: 256290001Sglebius *\li The number of seconds stored in an isc_time_t might be larger 257290001Sglebius * than the number of seconds a time_t is able to handle. Since 258290001Sglebius * time_t is mostly opaque according to the ANSI/ISO standard 259290001Sglebius * (essentially, all you can be sure of is that it is an arithmetic type, 260290001Sglebius * not even necessarily integral), it can be tricky to ensure that 261290001Sglebius * the isc_time_t is in the range a time_t can handle. Use this 262290001Sglebius * function in place of isc_time_seconds() any time you need to set a 263290001Sglebius * time_t from an isc_time_t. 264290001Sglebius * 265290001Sglebius * Requires: 266290001Sglebius *\li 't' is a valid pointer. 267290001Sglebius * 268290001Sglebius * Returns: 269290001Sglebius *\li Success 270290001Sglebius *\li Out of range 271290001Sglebius */ 272290001Sglebius 273290001Sglebiusisc_uint32_t 274290001Sglebiusisc_time_nanoseconds(const isc_time_t *t); 275290001Sglebius/*%< 276290001Sglebius * Return the number of nanoseconds stored in a time structure. 277290001Sglebius * 278290001Sglebius * Notes: 279290001Sglebius *\li This is the number of nanoseconds in excess of the number 280290001Sglebius * of seconds since the epoch; it will always be less than one 281290001Sglebius * full second. 282290001Sglebius * 283290001Sglebius * Requires: 284290001Sglebius *\li 't' is a valid pointer. 285290001Sglebius * 286290001Sglebius * Ensures: 287290001Sglebius *\li The returned value is less than 1*10^9. 288290001Sglebius */ 289290001Sglebius 290290001Sglebiusvoid 291290001Sglebiusisc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len); 292290001Sglebius/*%< 293290001Sglebius * Format the time 't' into the buffer 'buf' of length 'len', 294290001Sglebius * using a format like "30-Aug-2000 04:06:47.997" and the local time zone. 295290001Sglebius * If the text does not fit in the buffer, the result is indeterminate, 296290001Sglebius * but is always guaranteed to be null terminated. 297290001Sglebius * 298290001Sglebius * Requires: 299290001Sglebius *\li 'len' > 0 300290001Sglebius *\li 'buf' points to an array of at least len chars 301290001Sglebius * 302290001Sglebius */ 303290001Sglebius 304290001Sglebiusvoid 305290001Sglebiusisc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len); 306290001Sglebius/*%< 307290001Sglebius * Format the time 't' into the buffer 'buf' of length 'len', 308290001Sglebius * using a format like "Mon, 30 Aug 2000 04:06:47 GMT" 309290001Sglebius * If the text does not fit in the buffer, the result is indeterminate, 310290001Sglebius * but is always guaranteed to be null terminated. 311290001Sglebius * 312290001Sglebius * Requires: 313290001Sglebius *\li 'len' > 0 314290001Sglebius *\li 'buf' points to an array of at least len chars 315290001Sglebius * 316290001Sglebius */ 317290001Sglebius 318290001Sglebiusvoid 319290001Sglebiusisc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len); 320290001Sglebius/*%< 321290001Sglebius * Format the time 't' into the buffer 'buf' of length 'len', 322290001Sglebius * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ" 323290001Sglebius * If the text does not fit in the buffer, the result is indeterminate, 324290001Sglebius * but is always guaranteed to be null terminated. 325290001Sglebius * 326290001Sglebius * Requires: 327290001Sglebius *\li 'len' > 0 328290001Sglebius *\li 'buf' points to an array of at least len chars 329290001Sglebius * 330290001Sglebius */ 331290001Sglebius 332290001SglebiusISC_LANG_ENDDECLS 333290001Sglebius 334290001Sglebius#endif /* ISC_TIME_H */ 335