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 /* conversion between l_fp fractions and nanoseconds */
  60 #ifdef HAVE_U_INT64
  61 # define FTOTVN(tsf)                                            \
  62         ((int32)                                                \
  63          (((u_int64)(tsf) * NANOSECONDS + 0x80000000) >> 32))
  64 # define TVNTOF(tvu)                                            \
  65         ((u_int32)                                              \
  66          ((((u_int64)(tvu) << 32) + NANOSECONDS / 2) /          \
  67           NANOSECONDS))
  68 #else
  69 # define NSECFRAC       (FRAC / NANOSECONDS)
  70 # define FTOTVN(tsf)                                            \
  71         ((int32)((tsf) / NSECFRAC + 0.5))
  72 # define TVNTOF(tvu)                                            \
  73         ((u_int32)((tvu) * NSECFRAC + 0.5))
  74 #endif
  75
  76
  77
  78 /* make sure nanoseconds are in nominal range */
  79 static inline struct timespec
  80 normalize_tspec(
  81         struct timespec x
  82         )
  83 {
  84 #if SIZEOF_LONG > 4
  85         long    z;
  86
  87         /*
  88          * tv_nsec is of type 'long', and on a 64-bit machine using only
  89          * loops becomes prohibitive once the upper 32 bits get
  90          * involved. On the other hand, division by constant should be
  91          * fast enough; so we do a division of the nanoseconds in that
  92          * case. The floor adjustment step follows with the standard
  93          * normalisation loops. And labs() is intentionally not used
  94          * here: it has implementation-defined behaviour when applied
  95          * to LONG_MIN.
  96          */
  97         if (x.tv_nsec < -3l * NANOSECONDS ||
  98             x.tv_nsec > 3l * NANOSECONDS) {
  99                 z = x.tv_nsec / NANOSECONDS;
 100                 x.tv_nsec -= z * NANOSECONDS;
 101                 x.tv_sec += z;
 102         }
 103 #endif
 104         /* since 10**9 is close to 2**32, we don't divide but do a
 105          * normalisation in a loop; this takes 3 steps max, and should
 106          * outperform a division even if the mul-by-inverse trick is
 107          * employed. */
 108         if (x.tv_nsec < 0)
 109                 do {
 110                         x.tv_nsec += NANOSECONDS;
 111                         x.tv_sec--;
 112                 } while (x.tv_nsec < 0);
 113         else if (x.tv_nsec >= NANOSECONDS)
 114                 do {
 115                         x.tv_nsec -= NANOSECONDS;
 116                         x.tv_sec++;
 117                 } while (x.tv_nsec >= NANOSECONDS);
 118
 119         return x;
 120 }
 121
 122 /* x = a + b */
 123 static inline struct timespec
 124 add_tspec(
 125         struct timespec a,
 126         struct timespec b
 127         )
 128 {
 129         struct timespec x;
 130
 131         x = a;
 132         x.tv_sec += b.tv_sec;
 133         x.tv_nsec += b.tv_nsec;
 134
 135         return normalize_tspec(x);
 136 }
 137
 138 /* x = a + b, b is fraction only */
 139 static inline struct timespec
 140 add_tspec_ns(
 141         struct timespec a,
 142         long            b
 143         )
 144 {
 145         struct timespec x;
 146
 147         x = a;
 148         x.tv_nsec += b;
 149
 150         return normalize_tspec(x);
 151 }
 152
 153 /* x = a - b */
 154 static inline struct timespec
 155 sub_tspec(
 156         struct timespec a,
 157         struct timespec b
 158         )
 159 {
 160         struct timespec x;
 161
 162         x = a;
 163         x.tv_sec -= b.tv_sec;
 164         x.tv_nsec -= b.tv_nsec;
 165
 166         return normalize_tspec(x);
 167 }
 168
 169 /* x = a - b, b is fraction only */
 170 static inline struct timespec
 171 sub_tspec_ns(
 172         struct timespec a,
 173         long            b
 174         )
 175 {
 176         struct timespec x;
 177
 178         x = a;
 179         x.tv_nsec -= b;
 180
 181         return normalize_tspec(x);
 182 }
 183
 184 /* x = -a */
 185 static inline struct timespec
 186 neg_tspec(
 187         struct timespec a
 188         )
 189 {
 190         struct timespec x;
 191
 192         x.tv_sec = -a.tv_sec;
 193         x.tv_nsec = -a.tv_nsec;
 194
 195         return normalize_tspec(x);
 196 }
 197
 198 /* x = abs(a) */
 199 static inline struct timespec
 200 abs_tspec(
 201         struct timespec a
 202         )
 203 {
 204         struct timespec c;
 205
 206         c = normalize_tspec(a);
 207         if (c.tv_sec < 0) {
 208                 if (c.tv_nsec != 0) {
 209                         c.tv_sec = -c.tv_sec - 1;
 210                         c.tv_nsec = NANOSECONDS - c.tv_nsec;
 211                 } else {
 212                         c.tv_sec = -c.tv_sec;
 213                 }
 214         }
 215
 216         return c;
 217 }
 218
 219 /*
 220  * compare previously-normalised a and b
 221  * return 1 / 0 / -1 if a < / == / > b
 222  */
 223 static inline int
 224 cmp_tspec(
 225         struct timespec a,
 226         struct timespec b
 227         )
 228 {
 229         int r;
 230
 231         r = (a.tv_sec > b.tv_sec) - (a.tv_sec < b.tv_sec);
 232         if (0 == r)
 233                 r = (a.tv_nsec > b.tv_nsec) -
 234                     (a.tv_nsec < b.tv_nsec);
 235
 236         return r;
 237 }
 238
 239 /*
 240  * compare possibly-denormal a and b
 241  * return 1 / 0 / -1 if a < / == / > b
 242  */
 243 static inline int
 244 cmp_tspec_denorm(
 245         struct timespec a,
 246         struct timespec b
 247         )
 248 {
 249         return cmp_tspec(normalize_tspec(a), normalize_tspec(b));
 250 }
 251
 252 /*
 253  * test previously-normalised a
 254  * return 1 / 0 / -1 if a < / == / > 0
 255  */
 256 static inline int
 257 test_tspec(
 258         struct timespec a
 259         )
 260 {
 261         int             r;
 262
 263         r = (a.tv_sec > 0) - (a.tv_sec < 0);
 264         if (r == 0)
 265                 r = (a.tv_nsec > 0);
 266
 267         return r;
 268 }
 269
 270 /*
 271  * test possibly-denormal a
 272  * return 1 / 0 / -1 if a < / == / > 0
 273  */
 274 static inline int
 275 test_tspec_denorm(
 276         struct timespec a
 277         )
 278 {
 279         return test_tspec(normalize_tspec(a));
 280 }
 281
 282 /* return LIB buffer ptr to string rep */
 283 static inline const char *
 284 tspectoa(
 285         struct timespec x
 286         )
 287 {
 288         return format_time_fraction(x.tv_sec, x.tv_nsec, 9);
 289 }
 290
 291 /*
 292  *  convert to l_fp type, relative and absolute
 293  */
 294
 295 /* convert from timespec duration to l_fp duration */
 296 static inline l_fp
 297 tspec_intv_to_lfp(
 298         struct timespec x
 299         )
 300 {
 301         struct timespec v;
 302         l_fp            y;
 303
 304         v = normalize_tspec(x);
 305         y.l_uf = TVNTOF(v.tv_nsec);
 306         y.l_i = (int32)v.tv_sec;
 307
 308         return y;
 309 }
 310
 311 /* x must be UN*X epoch, output will be in NTP epoch */
 312 static inline l_fp
 313 tspec_stamp_to_lfp(
 314         struct timespec x
 315         )
 316 {
 317         l_fp            y;
 318
 319         y = tspec_intv_to_lfp(x);
 320         y.l_ui += JAN_1970;
 321
 322         return y;
 323 }
 324
 325 /* convert from l_fp type, relative signed/unsigned and absolute */
 326 static inline struct timespec
 327 lfp_intv_to_tspec(
 328         l_fp            x
 329         )
 330 {
 331         struct timespec out;
 332         l_fp            absx;
 333         int             neg;
 334
 335         neg = L_ISNEG(&x);
 336         absx = x;
 337         if (neg) {
 338                 L_NEG(&absx);
 339         }
 340         out.tv_nsec = FTOTVN(absx.l_uf);
 341         out.tv_sec = absx.l_i;
 342         if (neg) {
 343                 out.tv_sec = -out.tv_sec;
 344                 out.tv_nsec = -out.tv_nsec;
 345                 out = normalize_tspec(out);
 346         }
 347
 348         return out;
 349 }
 350
 351 static inline struct timespec
 352 lfp_uintv_to_tspec(
 353         l_fp            x
 354         )
 355 {
 356         struct timespec out;
 357
 358         out.tv_nsec = FTOTVN(x.l_uf);
 359         out.tv_sec = x.l_ui;
 360
 361         return out;
 362 }
 363
 364 /*
 365  * absolute (timestamp) conversion. Input is time in NTP epoch, output
 366  * is in UN*X epoch. The NTP time stamp will be expanded around the
 367  * pivot time *p or the current time, if p is NULL.
 368  */
 369 static inline struct timespec
 370 lfp_stamp_to_tspec(
 371         l_fp            x,
 372         const time_t *  p
 373         )
 374 {
 375         struct timespec out;
 376         vint64          sec;
 377
 378         sec = ntpcal_ntp_to_time(x.l_ui, p);
 379         out.tv_nsec = FTOTVN(x.l_uf);
 380
 381         /* copying a vint64 to a time_t needs some care... */
 382 #if SIZEOF_TIME_T <= 4
 383         out.tv_sec = (time_t)sec.d_s.lo;
 384 #elif defined(HAVE_INT64)
 385         out.tv_sec = (time_t)sec.q_s;
 386 #else
 387         out.tv_sec = ((time_t)sec.d_s.hi << 32) | sec.d_s.lo;
 388 #endif
 389
 390         return out;
 391 }
 392
 393 #endif  /* TIMESPECOPS_H */