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))
62 /* make sure nanoseconds are in nominal range */
63 extern struct timespec normalize_tspec(struct timespec x);
66 static inline struct timespec
76 x.tv_nsec += b.tv_nsec;
78 return normalize_tspec(x);
81 /* x = a + b, b is fraction only */
82 static inline struct timespec
93 return normalize_tspec(x);
97 static inline struct timespec
106 x.tv_sec -= b.tv_sec;
107 x.tv_nsec -= b.tv_nsec;
109 return normalize_tspec(x);
112 /* x = a - b, b is fraction only */
113 static inline struct timespec
124 return normalize_tspec(x);
128 static inline struct timespec
135 x.tv_sec = -a.tv_sec;
136 x.tv_nsec = -a.tv_nsec;
138 return normalize_tspec(x);
142 struct timespec abs_tspec(struct timespec a);
145 * compare previously-normalised a and b
146 * return 1 / 0 / -1 if a < / == / > b
148 extern int cmp_tspec(struct timespec a, struct timespec b);
151 * compare possibly-denormal a and b
152 * return 1 / 0 / -1 if a < / == / > b
160 return cmp_tspec(normalize_tspec(a), normalize_tspec(b));
164 * test previously-normalised a
165 * return 1 / 0 / -1 if a < / == / > 0
167 extern int test_tspec(struct timespec a);
170 * test possibly-denormal a
171 * return 1 / 0 / -1 if a < / == / > 0
178 return test_tspec(normalize_tspec(a));
181 /* return LIB buffer ptr to string rep */
182 static inline const char *
187 return format_time_fraction(x.tv_sec, x.tv_nsec, 9);
191 * convert to l_fp type, relative and absolute
194 /* convert from timespec duration to l_fp duration */
195 extern l_fp tspec_intv_to_lfp(struct timespec x);
197 /* x must be UN*X epoch, output will be in NTP epoch */
205 y = tspec_intv_to_lfp(x);
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);
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.
220 extern struct timespec lfp_stamp_to_tspec(l_fp x, const time_t *pivot);
222 #endif /* TIMESPECOPS_H */