xref: /freebsd/contrib/ntp/include/timespecops.h (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
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 */
223