util.h

   1 /*
   2   chronyd/chronyc - Programs for keeping computer clocks accurate.
   3
   4  **********************************************************************
   5  * Copyright (C) Richard P. Curnow  1997-2003
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of version 2 of the GNU General Public License as
   9  * published by the Free Software Foundation.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  19  *
  20  **********************************************************************
  21
  22   =======================================================================
  23
  24   Various utility functions
  25   */
  26
  27 #ifndef GOT_UTIL_H
  28 #define GOT_UTIL_H
  29
  30 #include "sysincl.h"
  31
  32 #include "addressing.h"
  33 #include "ntp.h"
  34 #include "candm.h"
  35 #include "cmac.h"
  36 #include "hash.h"
  37
  38 /* Zero a timespec */
  39 extern void UTI_ZeroTimespec(struct timespec *ts);
  40
  41 /* Check if a timespec is zero */
  42 extern int UTI_IsZeroTimespec(struct timespec *ts);
  43
  44 /* Convert a timeval into a timespec */
  45 extern void UTI_TimevalToTimespec(const struct timeval *tv, struct timespec *ts);
  46
  47 /* Convert a timespec into a timeval */
  48 extern void UTI_TimespecToTimeval(const struct timespec *ts, struct timeval *tv);
  49
  50 /* Convert a timespec into a floating point number of seconds */
  51 extern double UTI_TimespecToDouble(const struct timespec *ts);
  52
  53 /* Convert a number of seconds expressed in floating point into a
  54    timespec */
  55 extern void UTI_DoubleToTimespec(double d, struct timespec *ts);
  56
  57 /* Normalise a timespec, by adding or subtracting seconds to bring
  58    its nanosecond field into range */
  59 extern void UTI_NormaliseTimespec(struct timespec *ts);
  60
  61 /* Convert a timeval into a floating point number of seconds */
  62 extern double UTI_TimevalToDouble(const struct timeval *tv);
  63
  64 /* Convert a number of seconds expressed in floating point into a
  65    timeval */
  66 extern void UTI_DoubleToTimeval(double a, struct timeval *b);
  67
  68 /* Normalise a struct timeval, by adding or subtracting seconds to bring
  69    its microseconds field into range */
  70 extern void UTI_NormaliseTimeval(struct timeval *x);
  71
  72 /* Returns -1 if a comes earlier than b, 0 if a is the same time as b,
  73    and +1 if a comes after b */
  74 extern int UTI_CompareTimespecs(const struct timespec *a, const struct timespec *b);
  75
  76 /* Calculate result = a - b */
  77 extern void UTI_DiffTimespecs(struct timespec *result,
  78                               const struct timespec *a, const struct timespec *b);
  79
  80 /* Calculate result = a - b and return as a double */
  81 extern double UTI_DiffTimespecsToDouble(const struct timespec *a, const struct timespec *b);
  82
  83 /* Add a double increment to a timespec to get a new one. 'start' is
  84    the starting time, 'end' is the result that we return.  This is
  85    safe to use if start and end are the same */
  86 extern void UTI_AddDoubleToTimespec(const struct timespec *start, double increment,
  87                                     struct timespec *end);
  88
  89 /* Calculate the average and difference (as a double) of two timespecs */
  90 extern void UTI_AverageDiffTimespecs(const struct timespec *earlier, const struct timespec *later,
  91                                      struct timespec *average, double *diff);
  92
  93 /* Calculate result = a - b + c */
  94 extern void UTI_AddDiffToTimespec(const struct timespec *a, const struct timespec *b,
  95                                   const struct timespec *c, struct timespec *result);
  96
  97 /* Convert a timespec into a temporary string, largely for diagnostic
  98    display */
  99 extern char *UTI_TimespecToString(const struct timespec *ts);
 100
 101 /* Convert an NTP timestamp into a temporary string, largely for
 102    diagnostic display */
 103 extern char *UTI_Ntp64ToString(const NTP_int64 *ts);
 104
 105 /* Convert ref_id into a temporary string, for diagnostics */
 106 extern char *UTI_RefidToString(uint32_t ref_id);
 107
 108 /* Convert an IP address to string, for diagnostics */
 109 extern char *UTI_IPToString(const IPAddr *ip);
 110
 111 extern int UTI_StringToIP(const char *addr, IPAddr *ip);
 112 extern int UTI_IsStringIP(const char *string);
 113 extern int UTI_StringToIdIP(const char *addr, IPAddr *ip);
 114 extern int UTI_IsIPReal(const IPAddr *ip);
 115 extern uint32_t UTI_IPToRefid(const IPAddr *ip);
 116 extern uint32_t UTI_IPToHash(const IPAddr *ip);
 117 extern void UTI_IPHostToNetwork(const IPAddr *src, IPAddr *dest);
 118 extern void UTI_IPNetworkToHost(const IPAddr *src, IPAddr *dest);
 119 extern int UTI_CompareIPs(const IPAddr *a, const IPAddr *b, const IPAddr *mask);
 120
 121 extern char *UTI_IPSockAddrToString(const IPSockAddr *sa);
 122
 123 extern char *UTI_TimeToLogForm(time_t t);
 124
 125 /* Adjust time following a frequency/offset change */
 126 extern void UTI_AdjustTimespec(const struct timespec *old_ts, const struct timespec *when,
 127                                struct timespec *new_ts, double *delta_time,
 128                                double dfreq, double doffset);
 129
 130 /* Get zero NTP timestamp with random bits below precision */
 131 extern void UTI_GetNtp64Fuzz(NTP_int64 *ts, int precision);
 132
 133 extern double UTI_Ntp32ToDouble(NTP_int32 x);
 134 extern NTP_int32 UTI_DoubleToNtp32(double x);
 135
 136 /* Zero an NTP timestamp */
 137 extern void UTI_ZeroNtp64(NTP_int64 *ts);
 138
 139 /* Check if an NTP timestamp is zero */
 140 extern int UTI_IsZeroNtp64(const NTP_int64 *ts);
 141
 142 /* Compare two NTP timestamps.  Returns -1 if a is before b, 0 if a is equal to
 143    b, and 1 if a is after b. */
 144 extern int UTI_CompareNtp64(const NTP_int64 *a, const NTP_int64 *b);
 145
 146 /* Compare an NTP timestamp with up to three other timestamps.  Returns 0
 147    if a is not equal to any of b1, b2, and b3, 1 otherwise. */
 148 extern int UTI_IsEqualAnyNtp64(const NTP_int64 *a, const NTP_int64 *b1,
 149                                const NTP_int64 *b2, const NTP_int64 *b3);
 150
 151 /* Convert a timespec into an NTP timestamp */
 152 extern void UTI_TimespecToNtp64(const struct timespec *src, NTP_int64 *dest,
 153                                 const NTP_int64 *fuzz);
 154
 155 /* Convert an NTP timestamp into a timespec */
 156 extern void UTI_Ntp64ToTimespec(const NTP_int64 *src, struct timespec *dest);
 157
 158 /* Check if time + offset is sane */
 159 extern int UTI_IsTimeOffsetSane(const struct timespec *ts, double offset);
 160
 161 /* Get 2 raised to power of a signed integer */
 162 extern double UTI_Log2ToDouble(int l);
 163
 164 extern void UTI_TimespecNetworkToHost(const Timespec *src, struct timespec *dest);
 165 extern void UTI_TimespecHostToNetwork(const struct timespec *src, Timespec *dest);
 166
 167 extern double UTI_FloatNetworkToHost(Float x);
 168 extern Float UTI_FloatHostToNetwork(double x);
 169
 170 extern CMC_Algorithm UTI_CmacNameToAlgorithm(const char *name);
 171 extern HSH_Algorithm UTI_HashNameToAlgorithm(const char *name);
 172
 173 /* Set FD_CLOEXEC on descriptor */
 174 extern int UTI_FdSetCloexec(int fd);
 175
 176 extern void UTI_SetQuitSignalsHandler(void (*handler)(int), int ignore_sigpipe);
 177
 178 /* Get directory (as an allocated string) for a path */
 179 extern char *UTI_PathToDir(const char *path);
 180
 181 /* Create a directory with a specified mode (umasked) and set its uid/gid.
 182    Create also any parent directories that don't exist with mode 755 and
 183    default uid/gid.  Returns 1 if created or already exists (even with
 184    different mode/uid/gid), 0 otherwise. */
 185 extern int UTI_CreateDirAndParents(const char *path, mode_t mode, uid_t uid, gid_t gid);
 186
 187 /* Check if a directory is secure.  It must not have other than the specified
 188    permissions and its uid/gid must match the specified values. */
 189 extern int UTI_CheckDirPermissions(const char *path, mode_t perm, uid_t uid, gid_t gid);
 190
 191 /* Open a file.  The full path of the file is constructed from the basedir
 192    (may be NULL), '/' (if basedir is not NULL), name, and suffix (may be NULL).
 193    Created files have specified permissions (umasked).  Returns NULL on error.
 194    The following modes are supported (if the mode is an uppercase character,
 195    errors are fatal):
 196    r/R - open an existing file for reading
 197    w/W - open a new file for writing (remove existing file)
 198    a/A - open an existing file for appending (create if does not exist) */
 199 extern FILE *UTI_OpenFile(const char *basedir, const char *name, const char *suffix,
 200                           char mode, mode_t perm);
 201
 202 /* Rename a temporary file by changing its suffix.  The paths are constructed as
 203    in UTI_OpenFile().  If the renaming fails, the file will be removed. */
 204 extern int UTI_RenameTempFile(const char *basedir, const char *name,
 205                               const char *old_suffix, const char *new_suffix);
 206
 207 /* Remove a file.  The path is constructed as in UTI_OpenFile(). */
 208 extern int UTI_RemoveFile(const char *basedir, const char *name, const char *suffix);
 209
 210 /* Set process user/group IDs and drop supplementary groups */
 211 extern void UTI_DropRoot(uid_t uid, gid_t gid);
 212
 213 /* Fill buffer with random bytes from /dev/urandom */
 214 extern void UTI_GetRandomBytesUrandom(void *buf, unsigned int len);
 215
 216 /* Fill buffer with random bytes from /dev/urandom or a faster source if it's
 217    available (e.g. arc4random()), which may not necessarily be suitable for
 218    generating long-term keys */
 219 extern void UTI_GetRandomBytes(void *buf, unsigned int len);
 220
 221 /* Print data in hexadecimal format */
 222 extern int UTI_BytesToHex(const void *buf, unsigned int buf_len, char *hex, unsigned int hex_len);
 223
 224 /* Parse a string containing data in hexadecimal format.  In-place conversion
 225    is supported. */
 226 extern unsigned int UTI_HexToBytes(const char *hex, void *buf, unsigned int len);
 227
 228 /* Split a string into words separated by whitespace characters.  It returns
 229    the number of words found in the string, but saves only up to the specified
 230    number of pointers to the words. */
 231 extern int UTI_SplitString(char *string, char **words, int max_saved_words);
 232
 233 /* Macros to get maximum and minimum of two values */
 234 #ifdef MAX
 235 #undef MAX
 236 #endif
 237 #define MAX(x, y) ((x) > (y) ? (x) : (y))
 238 #ifdef MIN
 239 #undef MIN
 240 #endif
 241 #define MIN(x, y) ((x) < (y) ? (x) : (y))
 242
 243 /* Macro to clamp a value between two values */
 244 #define CLAMP(min, x, max) (MAX((min), MIN((x), (max))))
 245
 246 #define SQUARE(x) ((x) * (x))
 247
 248 #endif /* GOT_UTIL_H */