contrib/bind-9.3/lib/isc/unix/include/isc/time.h

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