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