1135446Strhodes/* 2262706Serwin * Copyright (C) 2004-2009, 2012, 2014 Internet Systems Consortium, Inc. ("ISC") 3135446Strhodes * Copyright (C) 1998-2001 Internet Software Consortium. 4135446Strhodes * 5193149Sdougb * Permission to use, copy, modify, and/or distribute this software for any 6135446Strhodes * purpose with or without fee is hereby granted, provided that the above 7135446Strhodes * copyright notice and this permission notice appear in all copies. 8135446Strhodes * 9135446Strhodes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10135446Strhodes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11135446Strhodes * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12135446Strhodes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13135446Strhodes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14135446Strhodes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15135446Strhodes * PERFORMANCE OF THIS SOFTWARE. 16135446Strhodes */ 17135446Strhodes 18234010Sdougb/* $Id: time.h,v 1.40 2009/01/05 23:47:54 tbox Exp $ */ 19135446Strhodes 20135446Strhodes#ifndef ISC_TIME_H 21135446Strhodes#define ISC_TIME_H 1 22135446Strhodes 23170222Sdougb/*! \file */ 24170222Sdougb 25135446Strhodes#include <isc/lang.h> 26135446Strhodes#include <isc/types.h> 27135446Strhodes 28135446Strhodes/*** 29135446Strhodes *** Intervals 30135446Strhodes ***/ 31135446Strhodes 32193149Sdougb/*! 33170222Sdougb * \brief 34135446Strhodes * The contents of this structure are private, and MUST NOT be accessed 35135446Strhodes * directly by callers. 36135446Strhodes * 37135446Strhodes * The contents are exposed only to allow callers to avoid dynamic allocation. 38135446Strhodes */ 39135446Strhodesstruct isc_interval { 40135446Strhodes unsigned int seconds; 41135446Strhodes unsigned int nanoseconds; 42135446Strhodes}; 43135446Strhodes 44254402Serwinextern const isc_interval_t * const isc_interval_zero; 45135446Strhodes 46135446StrhodesISC_LANG_BEGINDECLS 47135446Strhodes 48135446Strhodesvoid 49135446Strhodesisc_interval_set(isc_interval_t *i, 50135446Strhodes unsigned int seconds, unsigned int nanoseconds); 51170222Sdougb/*%< 52135446Strhodes * Set 'i' to a value representing an interval of 'seconds' seconds and 53135446Strhodes * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and 54135446Strhodes * isc_time_subtract(). 55135446Strhodes * 56135446Strhodes * Requires: 57135446Strhodes * 58170222Sdougb *\li 't' is a valid pointer. 59170222Sdougb *\li nanoseconds < 1000000000. 60135446Strhodes */ 61135446Strhodes 62135446Strhodesisc_boolean_t 63135446Strhodesisc_interval_iszero(const isc_interval_t *i); 64170222Sdougb/*%< 65135446Strhodes * Returns ISC_TRUE iff. 'i' is the zero interval. 66135446Strhodes * 67135446Strhodes * Requires: 68135446Strhodes * 69170222Sdougb *\li 'i' is a valid pointer. 70135446Strhodes */ 71135446Strhodes 72135446Strhodes/*** 73135446Strhodes *** Absolute Times 74135446Strhodes ***/ 75135446Strhodes 76170222Sdougb/*% 77135446Strhodes * The contents of this structure are private, and MUST NOT be accessed 78135446Strhodes * directly by callers. 79135446Strhodes * 80135446Strhodes * The contents are exposed only to allow callers to avoid dynamic allocation. 81135446Strhodes */ 82135446Strhodes 83135446Strhodesstruct isc_time { 84135446Strhodes unsigned int seconds; 85135446Strhodes unsigned int nanoseconds; 86135446Strhodes}; 87135446Strhodes 88254402Serwinextern const isc_time_t * const isc_time_epoch; 89135446Strhodes 90135446Strhodesvoid 91135446Strhodesisc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds); 92170222Sdougb/*%< 93193149Sdougb * Set 't' to a value which represents the given number of seconds and 94193149Sdougb * nanoseconds since 00:00:00 January 1, 1970, UTC. 95135446Strhodes * 96135446Strhodes * Notes: 97193149Sdougb *\li The Unix version of this call is equivalent to: 98170222Sdougb *\code 99135446Strhodes * isc_time_settoepoch(t); 100135446Strhodes * isc_interval_set(i, seconds, nanoseconds); 101135446Strhodes * isc_time_add(t, i, t); 102170222Sdougb *\endcode 103193149Sdougb * 104135446Strhodes * Requires: 105170222Sdougb *\li 't' is a valid pointer. 106170222Sdougb *\li nanoseconds < 1000000000. 107135446Strhodes */ 108135446Strhodes 109135446Strhodesvoid 110135446Strhodesisc_time_settoepoch(isc_time_t *t); 111170222Sdougb/*%< 112135446Strhodes * Set 't' to the time of the epoch. 113135446Strhodes * 114135446Strhodes * Notes: 115193149Sdougb *\li The date of the epoch is platform-dependent. 116135446Strhodes * 117135446Strhodes * Requires: 118135446Strhodes * 119170222Sdougb *\li 't' is a valid pointer. 120135446Strhodes */ 121135446Strhodes 122135446Strhodesisc_boolean_t 123135446Strhodesisc_time_isepoch(const isc_time_t *t); 124170222Sdougb/*%< 125135446Strhodes * Returns ISC_TRUE iff. 't' is the epoch ("time zero"). 126135446Strhodes * 127135446Strhodes * Requires: 128135446Strhodes * 129170222Sdougb *\li 't' is a valid pointer. 130135446Strhodes */ 131135446Strhodes 132135446Strhodesisc_result_t 133135446Strhodesisc_time_now(isc_time_t *t); 134170222Sdougb/*%< 135135446Strhodes * Set 't' to the current absolute time. 136135446Strhodes * 137135446Strhodes * Requires: 138135446Strhodes * 139170222Sdougb *\li 't' is a valid pointer. 140135446Strhodes * 141135446Strhodes * Returns: 142135446Strhodes * 143170222Sdougb *\li Success 144170222Sdougb *\li Unexpected error 145135446Strhodes * Getting the time from the system failed. 146170222Sdougb *\li Out of range 147135446Strhodes * The time from the system is too large to be represented 148135446Strhodes * in the current definition of isc_time_t. 149135446Strhodes */ 150135446Strhodes 151135446Strhodesisc_result_t 152135446Strhodesisc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i); 153170222Sdougb/*%< 154135446Strhodes * Set *t to the current absolute time + i. 155135446Strhodes * 156135446Strhodes * Note: 157170222Sdougb *\li This call is equivalent to: 158135446Strhodes * 159170222Sdougb *\code 160135446Strhodes * isc_time_now(t); 161135446Strhodes * isc_time_add(t, i, t); 162170222Sdougb *\endcode 163135446Strhodes * 164135446Strhodes * Requires: 165135446Strhodes * 166170222Sdougb *\li 't' and 'i' are valid pointers. 167135446Strhodes * 168135446Strhodes * Returns: 169135446Strhodes * 170170222Sdougb *\li Success 171170222Sdougb *\li Unexpected error 172135446Strhodes * Getting the time from the system failed. 173170222Sdougb *\li Out of range 174135446Strhodes * The interval added to the time from the system is too large to 175135446Strhodes * be represented in the current definition of isc_time_t. 176135446Strhodes */ 177135446Strhodes 178135446Strhodesint 179135446Strhodesisc_time_compare(const isc_time_t *t1, const isc_time_t *t2); 180170222Sdougb/*%< 181135446Strhodes * Compare the times referenced by 't1' and 't2' 182135446Strhodes * 183135446Strhodes * Requires: 184135446Strhodes * 185170222Sdougb *\li 't1' and 't2' are valid pointers. 186135446Strhodes * 187135446Strhodes * Returns: 188135446Strhodes * 189170222Sdougb *\li -1 t1 < t2 (comparing times, not pointers) 190170222Sdougb *\li 0 t1 = t2 191170222Sdougb *\li 1 t1 > t2 192135446Strhodes */ 193135446Strhodes 194135446Strhodesisc_result_t 195135446Strhodesisc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); 196170222Sdougb/*%< 197135446Strhodes * Add 'i' to 't', storing the result in 'result'. 198135446Strhodes * 199135446Strhodes * Requires: 200135446Strhodes * 201170222Sdougb *\li 't', 'i', and 'result' are valid pointers. 202135446Strhodes * 203135446Strhodes * Returns: 204193149Sdougb *\li Success 205170222Sdougb *\li Out of range 206135446Strhodes * The interval added to the time is too large to 207135446Strhodes * be represented in the current definition of isc_time_t. 208135446Strhodes */ 209135446Strhodes 210135446Strhodesisc_result_t 211135446Strhodesisc_time_subtract(const isc_time_t *t, const isc_interval_t *i, 212135446Strhodes isc_time_t *result); 213170222Sdougb/*%< 214135446Strhodes * Subtract 'i' from 't', storing the result in 'result'. 215135446Strhodes * 216135446Strhodes * Requires: 217135446Strhodes * 218170222Sdougb *\li 't', 'i', and 'result' are valid pointers. 219135446Strhodes * 220135446Strhodes * Returns: 221170222Sdougb *\li Success 222170222Sdougb *\li Out of range 223135446Strhodes * The interval is larger than the time since the epoch. 224135446Strhodes */ 225135446Strhodes 226135446Strhodesisc_uint64_t 227135446Strhodesisc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2); 228170222Sdougb/*%< 229135446Strhodes * Find the difference in microseconds between time t1 and time t2. 230135446Strhodes * t2 is the subtrahend of t1; ie, difference = t1 - t2. 231135446Strhodes * 232135446Strhodes * Requires: 233135446Strhodes * 234170222Sdougb *\li 't1' and 't2' are valid pointers. 235135446Strhodes * 236135446Strhodes * Returns: 237170222Sdougb *\li The difference of t1 - t2, or 0 if t1 <= t2. 238135446Strhodes */ 239135446Strhodes 240135446Strhodesisc_uint32_t 241135446Strhodesisc_time_seconds(const isc_time_t *t); 242170222Sdougb/*%< 243135446Strhodes * Return the number of seconds since the epoch stored in a time structure. 244135446Strhodes * 245135446Strhodes * Requires: 246135446Strhodes * 247170222Sdougb *\li 't' is a valid pointer. 248135446Strhodes */ 249135446Strhodes 250135446Strhodesisc_result_t 251135446Strhodesisc_time_secondsastimet(const isc_time_t *t, time_t *secondsp); 252170222Sdougb/*%< 253135446Strhodes * Ensure the number of seconds in an isc_time_t is representable by a time_t. 254135446Strhodes * 255135446Strhodes * Notes: 256170222Sdougb *\li The number of seconds stored in an isc_time_t might be larger 257135446Strhodes * than the number of seconds a time_t is able to handle. Since 258135446Strhodes * time_t is mostly opaque according to the ANSI/ISO standard 259135446Strhodes * (essentially, all you can be sure of is that it is an arithmetic type, 260135446Strhodes * not even necessarily integral), it can be tricky to ensure that 261135446Strhodes * the isc_time_t is in the range a time_t can handle. Use this 262135446Strhodes * function in place of isc_time_seconds() any time you need to set a 263135446Strhodes * time_t from an isc_time_t. 264135446Strhodes * 265135446Strhodes * Requires: 266170222Sdougb *\li 't' is a valid pointer. 267135446Strhodes * 268135446Strhodes * Returns: 269170222Sdougb *\li Success 270170222Sdougb *\li Out of range 271135446Strhodes */ 272135446Strhodes 273135446Strhodesisc_uint32_t 274135446Strhodesisc_time_nanoseconds(const isc_time_t *t); 275170222Sdougb/*%< 276135446Strhodes * Return the number of nanoseconds stored in a time structure. 277135446Strhodes * 278135446Strhodes * Notes: 279193149Sdougb *\li This is the number of nanoseconds in excess of the number 280135446Strhodes * of seconds since the epoch; it will always be less than one 281135446Strhodes * full second. 282135446Strhodes * 283135446Strhodes * Requires: 284170222Sdougb *\li 't' is a valid pointer. 285135446Strhodes * 286135446Strhodes * Ensures: 287170222Sdougb *\li The returned value is less than 1*10^9. 288135446Strhodes */ 289135446Strhodes 290135446Strhodesvoid 291135446Strhodesisc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len); 292170222Sdougb/*%< 293135446Strhodes * Format the time 't' into the buffer 'buf' of length 'len', 294135446Strhodes * using a format like "30-Aug-2000 04:06:47.997" and the local time zone. 295135446Strhodes * If the text does not fit in the buffer, the result is indeterminate, 296135446Strhodes * but is always guaranteed to be null terminated. 297135446Strhodes * 298135446Strhodes * Requires: 299170222Sdougb *\li 'len' > 0 300193149Sdougb *\li 'buf' points to an array of at least len chars 301135446Strhodes * 302135446Strhodes */ 303135446Strhodes 304193149Sdougbvoid 305193149Sdougbisc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len); 306193149Sdougb/*%< 307193149Sdougb * Format the time 't' into the buffer 'buf' of length 'len', 308193149Sdougb * using a format like "Mon, 30 Aug 2000 04:06:47 GMT" 309193149Sdougb * If the text does not fit in the buffer, the result is indeterminate, 310193149Sdougb * but is always guaranteed to be null terminated. 311193149Sdougb * 312193149Sdougb * Requires: 313193149Sdougb *\li 'len' > 0 314193149Sdougb *\li 'buf' points to an array of at least len chars 315193149Sdougb * 316193149Sdougb */ 317193149Sdougb 318262706Serwinisc_result_t 319262706Serwinisc_time_parsehttptimestamp(char *input, isc_time_t *t); 320262706Serwin/*%< 321262706Serwin * Parse the time in 'input' into the isc_time_t pointed to by 't', 322262706Serwin * expecting a format like "Mon, 30 Aug 2000 04:06:47 GMT" 323262706Serwin * 324262706Serwin * Requires: 325262706Serwin *\li 'buf' and 't' are not NULL. 326262706Serwin */ 327262706Serwin 328193149Sdougbvoid 329193149Sdougbisc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len); 330193149Sdougb/*%< 331193149Sdougb * Format the time 't' into the buffer 'buf' of length 'len', 332193149Sdougb * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ" 333193149Sdougb * If the text does not fit in the buffer, the result is indeterminate, 334193149Sdougb * but is always guaranteed to be null terminated. 335193149Sdougb * 336193149Sdougb * Requires: 337193149Sdougb *\li 'len' > 0 338193149Sdougb *\li 'buf' points to an array of at least len chars 339193149Sdougb * 340193149Sdougb */ 341193149Sdougb 342135446StrhodesISC_LANG_ENDDECLS 343135446Strhodes 344135446Strhodes#endif /* ISC_TIME_H */ 345