timespecops.h revision 358659 
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 */
63extern struct timespec normalize_tspec(struct timespec x);
64
65/* x = a + b */
66static inline struct timespec
67add_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 */
82static inline struct timespec
83add_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 */
97static inline struct timespec
98sub_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 */
113static inline struct timespec
114sub_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 */
128static inline struct timespec
129neg_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) */
142struct timespec abs_tspec(struct timespec a);
143
144/*
145 * compare previously-normalised a and b
146 * return 1 / 0 / -1 if a < / == / > b
147 */
148extern 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 */
154static inline int
155cmp_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 */
167extern int test_tspec(struct timespec a);
168
169/*
170 * test possibly-denormal a
171 * return 1 / 0 / -1 if a < / == / > 0
172 */
173static inline int
174test_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 */
182static inline const char *
183tspectoa(
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 */
195extern l_fp tspec_intv_to_lfp(struct timespec x);
196
197/* x must be UN*X epoch, output will be in NTP epoch */
198static inline l_fp
199tspec_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 */
212extern struct timespec lfp_intv_to_tspec(l_fp x);
213extern 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 */
220extern struct timespec lfp_stamp_to_tspec(l_fp x, const time_t *pivot);
221
222#endif	/* TIMESPECOPS_H */
223