contrib/ntp/include/timespecops.h

   1 /*
   2  * timespecops.h -- calculations on 'struct timespec' values
   3  *
   4  * Written by Juergen Perlinger (perlinger@ntp.org) for the NTP project.
   5  * The contents of 'html/copyright.html' apply.
   6  *
   7  * Rationale
   8  * ---------
   9  *
  10  * Doing basic arithmetic on a 'struct timespec' is not exceedingly
  11  * hard, but it requires tedious and repetitive code to keep the result
  12  * normalised. We consider a timespec normalised when the nanosecond
  13  * fraction is in the interval [0 .. 10^9[ ; there are multiple value
  14  * pairs of seconds and nanoseconds that denote the same time interval,
  15  * but the normalised representation is unique. No two different
  16  * intervals can have the same normalised representation.
  17  *
  18  * Another topic is the representation of negative time intervals.
  19  * There's more than one way to this, since both the seconds and the
  20  * nanoseconds of a timespec are signed values. IMHO, the easiest way is
  21  * to use a complement representation where the nanoseconds are still
  22  * normalised, no matter what the sign of the seconds value. This makes
  23  * normalisation easier, since the sign of the integer part is
  24  * irrelevant, and it removes several sign decision cases during the
  25  * calculations.
  26  *
  27  * As long as no signed integer overflow can occur with the nanosecond
  28  * part of the operands, all operations work as expected and produce a
  29  * normalised result.
  30  *
  31  * The exception to this are functions fix a '_fast' suffix, which do no
  32  * normalisation on input data and therefore expect the input data to be
  33  * normalised.
  34  *
  35  * Input and output operands may overlap; all input is consumed before
  36  * the output is written to.
  37  */
  38 #ifndef TIMESPECOPS_H
  39 #define TIMESPECOPS_H
  40
  41 #include <sys/types.h>
  42 #include <stdio.h>
  43 #include <math.h>
  44
  45 #include "ntp.h"
  46 #include "timetoa.h"
  47
  48
  49 /* nanoseconds per second */
  50 #define NANOSECONDS 1000000000
  51
  52 /* predicate: returns TRUE if the nanoseconds are in nominal range */
  53 #define timespec_isnormal(x) \
  54         ((x)->tv_nsec >= 0 && (x)->tv_nsec < NANOSECONDS)
  55
  56 /* predicate: returns TRUE if the nanoseconds are out-of-bounds */
  57 #define timespec_isdenormal(x)  (!timespec_isnormal(x))
  58
  59
  60
  61
  62 /* make sure nanoseconds are in nominal range */
  63 extern struct timespec normalize_tspec(struct timespec x);
  64
  65 /* x = a + b */
  66 static inline struct timespec
  67 add_tspec(
  68         struct timespec a,
  69         struct timespec b
  70         )
  71 {
  72         struct timespec x;
  73
  74         x = a;
  75         x.tv_sec += b.tv_sec;
  76         x.tv_nsec += b.tv_nsec;
  77
  78         return normalize_tspec(x);
  79 }
  80
  81 /* x = a + b, b is fraction only */
  82 static inline struct timespec
  83 add_tspec_ns(
  84         struct timespec a,
  85         long            b
  86         )
  87 {
  88         struct timespec x;
  89
  90         x = a;
  91         x.tv_nsec += b;
  92
  93         return normalize_tspec(x);
  94 }
  95
  96 /* x = a - b */
  97 static inline struct timespec
  98 sub_tspec(
  99         struct timespec a,
 100         struct timespec b
 101         )
 102 {
 103         struct timespec x;
 104
 105         x = a;
 106         x.tv_sec -= b.tv_sec;
 107         x.tv_nsec -= b.tv_nsec;
 108
 109         return normalize_tspec(x);
 110 }
 111
 112 /* x = a - b, b is fraction only */
 113 static inline struct timespec
 114 sub_tspec_ns(
 115         struct timespec a,
 116         long            b
 117         )
 118 {
 119         struct timespec x;
 120
 121         x = a;
 122         x.tv_nsec -= b;
 123
 124         return normalize_tspec(x);
 125 }
 126
 127 /* x = -a */
 128 static inline struct timespec
 129 neg_tspec(
 130         struct timespec a
 131         )
 132 {
 133         struct timespec x;
 134
 135         x.tv_sec = -a.tv_sec;
 136         x.tv_nsec = -a.tv_nsec;
 137
 138         return normalize_tspec(x);
 139 }
 140
 141 /* x = abs(a) */
 142 struct timespec abs_tspec(struct timespec a);
 143
 144 /*
 145  * compare previously-normalised a and b
 146  * return 1 / 0 / -1 if a < / == / > b
 147  */
 148 extern int cmp_tspec(struct timespec a, struct timespec b);
 149
 150 /*
 151  * compare possibly-denormal a and b
 152  * return 1 / 0 / -1 if a < / == / > b
 153  */
 154 static inline int
 155 cmp_tspec_denorm(
 156         struct timespec a,
 157         struct timespec b
 158         )
 159 {
 160         return cmp_tspec(normalize_tspec(a), normalize_tspec(b));
 161 }
 162
 163 /*
 164  * test previously-normalised a
 165  * return 1 / 0 / -1 if a < / == / > 0
 166  */
 167 extern int test_tspec(struct timespec a);
 168
 169 /*
 170  * test possibly-denormal a
 171  * return 1 / 0 / -1 if a < / == / > 0
 172  */
 173 static inline int
 174 test_tspec_denorm(
 175         struct timespec a
 176         )
 177 {
 178         return test_tspec(normalize_tspec(a));
 179 }
 180
 181 /* return LIB buffer ptr to string rep */
 182 static inline const char *
 183 tspectoa(
 184         struct timespec x
 185         )
 186 {
 187         return format_time_fraction(x.tv_sec, x.tv_nsec, 9);
 188 }
 189
 190 /*
 191  *  convert to l_fp type, relative and absolute
 192  */
 193
 194 /* convert from timespec duration to l_fp duration */
 195 extern l_fp tspec_intv_to_lfp(struct timespec x);
 196
 197 /* x must be UN*X epoch, output will be in NTP epoch */
 198 static inline l_fp
 199 tspec_stamp_to_lfp(
 200         struct timespec x
 201         )
 202 {
 203         l_fp            y;
 204
 205         y = tspec_intv_to_lfp(x);
 206         y.l_ui += JAN_1970;
 207
 208         return y;
 209 }
 210
 211 /* convert from l_fp type, relative signed/unsigned and absolute */
 212 extern struct timespec lfp_intv_to_tspec(l_fp x);
 213 extern struct timespec lfp_uintv_to_tspec(l_fp x);
 214
 215 /*
 216  * absolute (timestamp) conversion. Input is time in NTP epoch, output
 217  * is in UN*X epoch. The NTP time stamp will be expanded around the
 218  * pivot time *p or the current time, if p is NULL.
 219  */
 220 extern struct timespec lfp_stamp_to_tspec(l_fp x, const time_t *pivot);
 221
 222 #endif  /* TIMESPECOPS_H */