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

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