contrib/bind9/lib/isc/unix/include/isc/time.h

   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  */
  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 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
 109 void
 110 isc_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
 122 isc_boolean_t
 123 isc_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
 132 isc_result_t
 133 isc_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
 151 isc_result_t
 152 isc_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
 178 int
 179 isc_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
 194 isc_result_t
 195 isc_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
 210 isc_result_t
 211 isc_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
 226 isc_uint64_t
 227 isc_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
 240 isc_uint32_t
 241 isc_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
 250 isc_result_t
 251 isc_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
 273 isc_uint32_t
 274 isc_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
 290 void
 291 isc_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
 304 void
 305 isc_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
 318 void
 319 isc_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
 332 ISC_LANG_ENDDECLS
 333
 334 #endif /* ISC_TIME_H */