external/bsd/ntp/dist/lib/isc/unix/include/isc/time.h

   1 /*      $NetBSD$        */
   2
   3 /*
   4  * Copyright (C) 2004-2009  Internet Systems Consortium, Inc. ("ISC")
   5  * Copyright (C) 1998-2001  Internet Software Consortium.
   6  *
   7  * Permission to use, copy, modify, and/or distribute this software for any
   8  * purpose with or without fee is hereby granted, provided that the above
   9  * copyright notice and this permission notice appear in all copies.
  10  *
  11  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  * PERFORMANCE OF THIS SOFTWARE.
  18  */
  19
  20 /* Id: time.h,v 1.38.56.2 2009/01/05 23:47:23 tbox Exp */
  21
  22 #ifndef ISC_TIME_H
  23 #define ISC_TIME_H 1
  24
  25 /*! \file */
  26
  27 #include <isc/lang.h>
  28 #include <isc/types.h>
  29
  30 /***
  31  *** Intervals
  32  ***/
  33
  34 /*!
  35  *  \brief
  36  * The contents of this structure are private, and MUST NOT be accessed
  37  * directly by callers.
  38  *
  39  * The contents are exposed only to allow callers to avoid dynamic allocation.
  40  */
  41 struct isc_interval {
  42         unsigned int seconds;
  43         unsigned int nanoseconds;
  44 };
  45
  46 extern isc_interval_t *isc_interval_zero;
  47
  48 ISC_LANG_BEGINDECLS
  49
  50 void
  51 isc_interval_set(isc_interval_t *i,
  52                  unsigned int seconds, unsigned int nanoseconds);
  53 /*%<
  54  * Set 'i' to a value representing an interval of 'seconds' seconds and
  55  * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and
  56  * isc_time_subtract().
  57  *
  58  * Requires:
  59  *
  60  *\li   't' is a valid pointer.
  61  *\li   nanoseconds < 1000000000.
  62  */
  63
  64 isc_boolean_t
  65 isc_interval_iszero(const isc_interval_t *i);
  66 /*%<
  67  * Returns ISC_TRUE iff. 'i' is the zero interval.
  68  *
  69  * Requires:
  70  *
  71  *\li   'i' is a valid pointer.
  72  */
  73
  74 /***
  75  *** Absolute Times
  76  ***/
  77
  78 /*%
  79  * The contents of this structure are private, and MUST NOT be accessed
  80  * directly by callers.
  81  *
  82  * The contents are exposed only to allow callers to avoid dynamic allocation.
  83  */
  84
  85 struct isc_time {
  86         unsigned int    seconds;
  87         unsigned int    nanoseconds;
  88 };
  89
  90 extern isc_time_t *isc_time_epoch;
  91
  92 void
  93 isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds);
  94 /*%<
  95  * Set 't' to a value which represents the given number of seconds and
  96  * nanoseconds since 00:00:00 January 1, 1970, UTC.
  97  *
  98  * Notes:
  99  *\li   The Unix version of this call is equivalent to:
 100  *\code
 101  *      isc_time_settoepoch(t);
 102  *      isc_interval_set(i, seconds, nanoseconds);
 103  *      isc_time_add(t, i, t);
 104  *\endcode
 105  *
 106  * Requires:
 107  *\li   't' is a valid pointer.
 108  *\li   nanoseconds < 1000000000.
 109  */
 110
 111 void
 112 isc_time_settoepoch(isc_time_t *t);
 113 /*%<
 114  * Set 't' to the time of the epoch.
 115  *
 116  * Notes:
 117  *\li   The date of the epoch is platform-dependent.
 118  *
 119  * Requires:
 120  *
 121  *\li   't' is a valid pointer.
 122  */
 123
 124 isc_boolean_t
 125 isc_time_isepoch(const isc_time_t *t);
 126 /*%<
 127  * Returns ISC_TRUE iff. 't' is the epoch ("time zero").
 128  *
 129  * Requires:
 130  *
 131  *\li   't' is a valid pointer.
 132  */
 133
 134 isc_result_t
 135 isc_time_now(isc_time_t *t);
 136 /*%<
 137  * Set 't' to the current absolute time.
 138  *
 139  * Requires:
 140  *
 141  *\li   't' is a valid pointer.
 142  *
 143  * Returns:
 144  *
 145  *\li   Success
 146  *\li   Unexpected error
 147  *              Getting the time from the system failed.
 148  *\li   Out of range
 149  *              The time from the system is too large to be represented
 150  *              in the current definition of isc_time_t.
 151  */
 152
 153 isc_result_t
 154 isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i);
 155 /*%<
 156  * Set *t to the current absolute time + i.
 157  *
 158  * Note:
 159  *\li   This call is equivalent to:
 160  *
 161  *\code
 162  *              isc_time_now(t);
 163  *              isc_time_add(t, i, t);
 164  *\endcode
 165  *
 166  * Requires:
 167  *
 168  *\li   't' and 'i' are valid pointers.
 169  *
 170  * Returns:
 171  *
 172  *\li   Success
 173  *\li   Unexpected error
 174  *              Getting the time from the system failed.
 175  *\li   Out of range
 176  *              The interval added to the time from the system is too large to
 177  *              be represented in the current definition of isc_time_t.
 178  */
 179
 180 int
 181 isc_time_compare(const isc_time_t *t1, const isc_time_t *t2);
 182 /*%<
 183  * Compare the times referenced by 't1' and 't2'
 184  *
 185  * Requires:
 186  *
 187  *\li   't1' and 't2' are valid pointers.
 188  *
 189  * Returns:
 190  *
 191  *\li   -1              t1 < t2         (comparing times, not pointers)
 192  *\li   0               t1 = t2
 193  *\li   1               t1 > t2
 194  */
 195
 196 isc_result_t
 197 isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result);
 198 /*%<
 199  * Add 'i' to 't', storing the result in 'result'.
 200  *
 201  * Requires:
 202  *
 203  *\li   't', 'i', and 'result' are valid pointers.
 204  *
 205  * Returns:
 206  *\li   Success
 207  *\li   Out of range
 208  *              The interval added to the time is too large to
 209  *              be represented in the current definition of isc_time_t.
 210  */
 211
 212 isc_result_t
 213 isc_time_subtract(const isc_time_t *t, const isc_interval_t *i,
 214                   isc_time_t *result);
 215 /*%<
 216  * Subtract 'i' from 't', storing the result in 'result'.
 217  *
 218  * Requires:
 219  *
 220  *\li   't', 'i', and 'result' are valid pointers.
 221  *
 222  * Returns:
 223  *\li   Success
 224  *\li   Out of range
 225  *              The interval is larger than the time since the epoch.
 226  */
 227
 228 isc_uint64_t
 229 isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2);
 230 /*%<
 231  * Find the difference in microseconds between time t1 and time t2.
 232  * t2 is the subtrahend of t1; ie, difference = t1 - t2.
 233  *
 234  * Requires:
 235  *
 236  *\li   't1' and 't2' are valid pointers.
 237  *
 238  * Returns:
 239  *\li   The difference of t1 - t2, or 0 if t1 <= t2.
 240  */
 241
 242 isc_uint32_t
 243 isc_time_seconds(const isc_time_t *t);
 244 /*%<
 245  * Return the number of seconds since the epoch stored in a time structure.
 246  *
 247  * Requires:
 248  *
 249  *\li   't' is a valid pointer.
 250  */
 251
 252 isc_result_t
 253 isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp);
 254 /*%<
 255  * Ensure the number of seconds in an isc_time_t is representable by a time_t.
 256  *
 257  * Notes:
 258  *\li   The number of seconds stored in an isc_time_t might be larger
 259  *      than the number of seconds a time_t is able to handle.  Since
 260  *      time_t is mostly opaque according to the ANSI/ISO standard
 261  *      (essentially, all you can be sure of is that it is an arithmetic type,
 262  *      not even necessarily integral), it can be tricky to ensure that
 263  *      the isc_time_t is in the range a time_t can handle.  Use this
 264  *      function in place of isc_time_seconds() any time you need to set a
 265  *      time_t from an isc_time_t.
 266  *
 267  * Requires:
 268  *\li   't' is a valid pointer.
 269  *
 270  * Returns:
 271  *\li   Success
 272  *\li   Out of range
 273  */
 274
 275 isc_uint32_t
 276 isc_time_nanoseconds(const isc_time_t *t);
 277 /*%<
 278  * Return the number of nanoseconds stored in a time structure.
 279  *
 280  * Notes:
 281  *\li   This is the number of nanoseconds in excess of the number
 282  *      of seconds since the epoch; it will always be less than one
 283  *      full second.
 284  *
 285  * Requires:
 286  *\li   't' is a valid pointer.
 287  *
 288  * Ensures:
 289  *\li   The returned value is less than 1*10^9.
 290  */
 291
 292 void
 293 isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len);
 294 /*%<
 295  * Format the time 't' into the buffer 'buf' of length 'len',
 296  * using a format like "30-Aug-2000 04:06:47.997" and the local time zone.
 297  * If the text does not fit in the buffer, the result is indeterminate,
 298  * but is always guaranteed to be null terminated.
 299  *
 300  *  Requires:
 301  *\li      'len' > 0
 302  *\li      'buf' points to an array of at least len chars
 303  *
 304  */
 305
 306 void
 307 isc_time_formathttptimestamp(const isc_time_t *t, char *buf, unsigned int len);
 308 /*%<
 309  * Format the time 't' into the buffer 'buf' of length 'len',
 310  * using a format like "Mon, 30 Aug 2000 04:06:47 GMT"
 311  * If the text does not fit in the buffer, the result is indeterminate,
 312  * but is always guaranteed to be null terminated.
 313  *
 314  *  Requires:
 315  *\li      'len' > 0
 316  *\li      'buf' points to an array of at least len chars
 317  *
 318  */
 319
 320 void
 321 isc_time_formatISO8601(const isc_time_t *t, char *buf, unsigned int len);
 322 /*%<
 323  * Format the time 't' into the buffer 'buf' of length 'len',
 324  * using the ISO8601 format: "yyyy-mm-ddThh:mm:ssZ"
 325  * If the text does not fit in the buffer, the result is indeterminate,
 326  * but is always guaranteed to be null terminated.
 327  *
 328  *  Requires:
 329  *\li      'len' > 0
 330  *\li      'buf' points to an array of at least len chars
 331  *
 332  */
 333
 334 ISC_LANG_ENDDECLS
 335
 336 #endif /* ISC_TIME_H */