home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / time.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  7.0 KB  |  305 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  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.30.18.2 2005/04/29 00:17:10 marka 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 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. ISC_LANG_ENDDECLS
  303.  
  304. #endif /* ISC_TIME_H */
  305.