2 * timespecops.h -- calculations on 'struct timespec' values
4 * Written by Juergen Perlinger (perlinger@ntp.org) for the NTP project.
5 * The contents of 'html/copyright.html' apply.
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.
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
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
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
35 * Input and output operands may overlap; all input is consumed before
36 * the output is written to.
41 #include <sys/types.h>
49 /* nanoseconds per second */
50 #define NANOSECONDS 1000000000
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)
56 /* predicate: returns TRUE if the nanoseconds are out-of-bounds */
57 #define timespec_isdenormal(x) (!timespec_isnormal(x))
59 /* conversion between l_fp fractions and nanoseconds */
61 # define FTOTVN(tsf) \
63 (((u_int64)(tsf) * NANOSECONDS + 0x80000000) >> 32))
64 # define TVNTOF(tvu) \
66 ((((u_int64)(tvu) << 32) + NANOSECONDS / 2) / \
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))
78 /* make sure nanoseconds are in nominal range */
79 static inline struct timespec
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
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;
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
110 x.tv_nsec += NANOSECONDS;
112 } while (x.tv_nsec < 0);
113 else if (x.tv_nsec >= NANOSECONDS)
115 x.tv_nsec -= NANOSECONDS;
117 } while (x.tv_nsec >= NANOSECONDS);
123 static inline struct timespec
132 x.tv_sec += b.tv_sec;
133 x.tv_nsec += b.tv_nsec;
135 return normalize_tspec(x);
138 /* x = a + b, b is fraction only */
139 static inline struct timespec
150 return normalize_tspec(x);
154 static inline struct timespec
163 x.tv_sec -= b.tv_sec;
164 x.tv_nsec -= b.tv_nsec;
166 return normalize_tspec(x);
169 /* x = a - b, b is fraction only */
170 static inline struct timespec
181 return normalize_tspec(x);
185 static inline struct timespec
192 x.tv_sec = -a.tv_sec;
193 x.tv_nsec = -a.tv_nsec;
195 return normalize_tspec(x);
199 static inline struct timespec
206 c = normalize_tspec(a);
208 if (c.tv_nsec != 0) {
209 c.tv_sec = -c.tv_sec - 1;
210 c.tv_nsec = NANOSECONDS - c.tv_nsec;
212 c.tv_sec = -c.tv_sec;
220 * compare previously-normalised a and b
221 * return 1 / 0 / -1 if a < / == / > b
231 r = (a.tv_sec > b.tv_sec) - (a.tv_sec < b.tv_sec);
233 r = (a.tv_nsec > b.tv_nsec) -
234 (a.tv_nsec < b.tv_nsec);
240 * compare possibly-denormal a and b
241 * return 1 / 0 / -1 if a < / == / > b
249 return cmp_tspec(normalize_tspec(a), normalize_tspec(b));
253 * test previously-normalised a
254 * return 1 / 0 / -1 if a < / == / > 0
263 r = (a.tv_sec > 0) - (a.tv_sec < 0);
271 * test possibly-denormal a
272 * return 1 / 0 / -1 if a < / == / > 0
279 return test_tspec(normalize_tspec(a));
282 /* return LIB buffer ptr to string rep */
283 static inline const char *
288 return format_time_fraction(x.tv_sec, x.tv_nsec, 9);
292 * convert to l_fp type, relative and absolute
295 /* convert from timespec duration to l_fp duration */
304 v = normalize_tspec(x);
305 y.l_uf = TVNTOF(v.tv_nsec);
306 y.l_i = (int32)v.tv_sec;
311 /* x must be UN*X epoch, output will be in NTP epoch */
319 y = tspec_intv_to_lfp(x);
325 /* convert from l_fp type, relative signed/unsigned and absolute */
326 static inline struct timespec
340 out.tv_nsec = FTOTVN(absx.l_uf);
341 out.tv_sec = absx.l_i;
343 out.tv_sec = -out.tv_sec;
344 out.tv_nsec = -out.tv_nsec;
345 out = normalize_tspec(out);
351 static inline struct timespec
358 out.tv_nsec = FTOTVN(x.l_uf);
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.
369 static inline struct timespec
378 sec = ntpcal_ntp_to_time(x.l_ui, p);
379 out.tv_nsec = FTOTVN(x.l_uf);
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;
387 out.tv_sec = ((time_t)sec.d_s.hi << 32) | sec.d_s.lo;
393 #endif /* TIMESPECOPS_H */