src/internal.h

   1 /*
   2  * internal.h: internal definitions just used by code from the library
   3  *
   4  * Copyright (C) 2006-2014 Red Hat, Inc.
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library.  If not, see
  18  * <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #pragma once
  22
  23 #include <errno.h>
  24 #include <limits.h>
  25 #include <verify.h>
  26 #include <stdbool.h>
  27 #include <stdint.h>
  28 #include <stdio.h>
  29 #include <string.h>
  30
  31 #if STATIC_ANALYSIS
  32 # undef NDEBUG /* Don't let a prior NDEBUG definition cause trouble.  */
  33 # include <assert.h>
  34 # define sa_assert(expr) assert (expr)
  35 #else
  36 # define sa_assert(expr) /* empty */
  37 #endif
  38
  39 /* The library itself is allowed to use deprecated functions /
  40  * variables, so effectively undefine the deprecated attribute
  41  * which would otherwise be defined in libvirt.h.
  42  */
  43 #undef VIR_DEPRECATED
  44 #define VIR_DEPRECATED /*empty*/
  45
  46 /* The library itself needs to know enum sizes.  */
  47 #define VIR_ENUM_SENTINELS
  48
  49 #ifdef HAVE_LIBINTL_H
  50 # define DEFAULT_TEXT_DOMAIN PACKAGE
  51 # include <libintl.h>
  52 # define _(str) dgettext(PACKAGE, str)
  53 #else /* HAVE_LIBINTL_H */
  54 # define _(str) str
  55 #endif /* HAVE_LIBINTL_H */
  56 #define N_(str) str
  57
  58 #include "libvirt/libvirt.h"
  59 #include "libvirt/libvirt-lxc.h"
  60 #include "libvirt/libvirt-qemu.h"
  61 #include "libvirt/libvirt-admin.h"
  62 #include "libvirt/virterror.h"
  63
  64 #include "c-strcase.h"
  65 #include "ignore-value.h"
  66 #include "count-leading-zeros.h"
  67
  68 /* String equality tests, suggested by Jim Meyering. */
  69 #define STREQ(a, b) (strcmp(a, b) == 0)
  70 #define STRCASEEQ(a, b) (c_strcasecmp(a, b) == 0)
  71 #define STRNEQ(a, b) (strcmp(a, b) != 0)
  72 #define STRCASENEQ(a, b) (c_strcasecmp(a, b) != 0)
  73 #define STREQLEN(a, b, n) (strncmp(a, b, n) == 0)
  74 #define STRCASEEQLEN(a, b, n) (c_strncasecmp(a, b, n) == 0)
  75 #define STRNEQLEN(a, b, n) (strncmp(a, b, n) != 0)
  76 #define STRCASENEQLEN(a, b, n) (c_strncasecmp(a, b, n) != 0)
  77 #define STRPREFIX(a, b) (strncmp(a, b, strlen(b)) == 0)
  78 #define STRCASEPREFIX(a, b) (c_strncasecmp(a, b, strlen(b)) == 0)
  79 #define STRSKIP(a, b) (STRPREFIX(a, b) ? (a) + strlen(b) : NULL)
  80
  81 #define STREQ_NULLABLE(a, b) \
  82     ((a) ? (b) && STREQ((a), (b)) : !(b))
  83 #define STRNEQ_NULLABLE(a, b) \
  84     ((a) ? !(b) || STRNEQ((a), (b)) : !!(b))
  85
  86 #define NUL_TERMINATE(buf) do { (buf)[sizeof(buf)-1] = '\0'; } while (0)
  87 #define ARRAY_CARDINALITY(Array) (sizeof(Array) / sizeof(*(Array)))
  88
  89 /**
  90  * ATTRIBUTE_UNUSED:
  91  *
  92  * Macro to flag consciously unused parameters to functions
  93  */
  94 #ifndef ATTRIBUTE_UNUSED
  95 # define ATTRIBUTE_UNUSED __attribute__((__unused__))
  96 #endif
  97
  98 /**
  99  * ATTRIBUTE_NORETURN:
 100  *
 101  * Macro to indicate that a function won't return to the caller
 102  */
 103 #ifndef ATTRIBUTE_NORETURN
 104 # define ATTRIBUTE_NORETURN __attribute__((__noreturn__))
 105 #endif
 106
 107 /**
 108  * ATTRIBUTE_SENTINEL:
 109  *
 110  * Macro to check for NULL-terminated varargs lists
 111  */
 112 #ifndef ATTRIBUTE_SENTINEL
 113 # define ATTRIBUTE_SENTINEL __attribute__((__sentinel__))
 114 #endif
 115
 116 /**
 117  * ATTRIBUTE_NOINLINE:
 118  *
 119  * Force compiler not to inline a method. Should be used if
 120  * the method need to be overridable by test mocks.
 121  */
 122 #ifndef ATTRIBUTE_NOINLINE
 123 # define ATTRIBUTE_NOINLINE __attribute__((__noinline__))
 124 #endif
 125
 126 /**
 127  * ATTRIBUTE_FMT_PRINTF
 128  *
 129  * Macro used to check printf like functions, if compiling
 130  * with gcc.
 131  *
 132  * We use gnulib which guarantees we always have GNU style
 133  * printf format specifiers even on broken Win32 platforms
 134  * hence we have to force 'gnu_printf' for new GCC
 135  */
 136 #ifndef ATTRIBUTE_FMT_PRINTF
 137 # ifndef __clang__
 138 #  define ATTRIBUTE_FMT_PRINTF(fmtpos, argpos) \
 139        __attribute__((__format__ (__gnu_printf__, fmtpos, argpos)))
 140 # else
 141 #  define ATTRIBUTE_FMT_PRINTF(fmtpos, argpos) \
 142        __attribute__((__format__ (__printf__, fmtpos, argpos)))
 143 # endif
 144 #endif
 145
 146 #ifndef ATTRIBUTE_RETURN_CHECK
 147 # define ATTRIBUTE_RETURN_CHECK __attribute__((__warn_unused_result__))
 148 #endif
 149
 150 /**
 151  * ATTRIBUTE_PACKED
 152  *
 153  * force a structure to be packed, i.e. not following architecture and
 154  * compiler best alignments for its sub components. It's needed for example
 155  * for the network filetering code when defining the content of raw
 156  * ethernet packets.
 157  * Others compiler than gcc may use something different e.g. #pragma pack(1)
 158  */
 159 #ifndef ATTRIBUTE_PACKED
 160 # define ATTRIBUTE_PACKED __attribute__((packed))
 161 #endif
 162
 163 /* gcc's handling of attribute nonnull is less than stellar - it does
 164  * NOT improve diagnostics, and merely allows gcc to optimize away
 165  * null code checks even when the caller manages to pass null in spite
 166  * of the attribute, leading to weird crashes.  Coverity, on the other
 167  * hand, knows how to do better static analysis based on knowing
 168  * whether a parameter is nonnull.  Make this attribute conditional
 169  * based on whether we are compiling for real or for analysis, while
 170  * still requiring correct gcc syntax when it is turned off.  See also
 171  * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=17308 */
 172 #ifndef ATTRIBUTE_NONNULL
 173 # if STATIC_ANALYSIS
 174 #  define ATTRIBUTE_NONNULL(m) __attribute__((__nonnull__(m)))
 175 # else
 176 #  define ATTRIBUTE_NONNULL(m) __attribute__(())
 177 # endif
 178 #endif
 179
 180 #ifndef ATTRIBUTE_FALLTHROUGH
 181 # if __GNUC_PREREQ (7, 0)
 182 #  define ATTRIBUTE_FALLTHROUGH __attribute__((fallthrough))
 183 # else
 184 #  define ATTRIBUTE_FALLTHROUGH do {} while(0)
 185 # endif
 186 #endif
 187
 188 #if WORKING_PRAGMA_PUSH
 189 # define VIR_WARNINGS_NO_CAST_ALIGN \
 190     _Pragma ("GCC diagnostic push") \
 191     _Pragma ("GCC diagnostic ignored \"-Wcast-align\"")
 192
 193 # define VIR_WARNINGS_NO_DEPRECATED \
 194     _Pragma ("GCC diagnostic push") \
 195     _Pragma ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
 196
 197 # if HAVE_SUGGEST_ATTRIBUTE_FORMAT
 198 #  define VIR_WARNINGS_NO_PRINTF \
 199     _Pragma ("GCC diagnostic push") \
 200     _Pragma ("GCC diagnostic ignored \"-Wsuggest-attribute=format\"")
 201 # else
 202 #  define VIR_WARNINGS_NO_PRINTF \
 203     _Pragma ("GCC diagnostic push")
 204 # endif
 205
 206 /* Workaround bogus GCC 6.0 for logical 'or' equal expression warnings.
 207  * (GCC bz 69602) */
 208 # if BROKEN_GCC_WLOGICALOP_EQUAL_EXPR
 209 #  define VIR_WARNINGS_NO_WLOGICALOP_EQUAL_EXPR \
 210      _Pragma ("GCC diagnostic push") \
 211      _Pragma ("GCC diagnostic ignored \"-Wlogical-op\"")
 212 # else
 213 #  define VIR_WARNINGS_NO_WLOGICALOP_EQUAL_EXPR \
 214      _Pragma ("GCC diagnostic push")
 215 # endif
 216
 217 # define VIR_WARNINGS_RESET \
 218     _Pragma ("GCC diagnostic pop")
 219 #else
 220 # define VIR_WARNINGS_NO_CAST_ALIGN
 221 # define VIR_WARNINGS_NO_DEPRECATED
 222 # define VIR_WARNINGS_NO_PRINTF
 223 # define VIR_WARNINGS_NO_WLOGICALOP_EQUAL_EXPR
 224 # define VIR_WARNINGS_RESET
 225 #endif
 226
 227 /* Workaround bogus GCC < 4.6 that produces false -Wlogical-op warnings for
 228  * strchr(). Those old GCCs don't support push/pop. */
 229 #if BROKEN_GCC_WLOGICALOP_STRCHR
 230 # define VIR_WARNINGS_NO_WLOGICALOP_STRCHR \
 231     _Pragma ("GCC diagnostic ignored \"-Wlogical-op\"")
 232 #else
 233 # define VIR_WARNINGS_NO_WLOGICALOP_STRCHR
 234 #endif
 235
 236
 237 /*
 238  * Use this when passing possibly-NULL strings to printf-a-likes.
 239  */
 240 #define NULLSTR(s) ((s) ? (s) : "<null>")
 241
 242 /*
 243  * Turn a NULL string into an empty string
 244  */
 245 #define NULLSTR_EMPTY(s) ((s) ? (s) : "")
 246
 247 /*
 248  * Turn a NULL string into a star
 249  */
 250 #define NULLSTR_STAR(s) ((s) ? (s) : "*")
 251
 252 /*
 253  * Turn a NULL string into a minus sign
 254  */
 255 #define NULLSTR_MINUS(s) ((s) ? (s) : "-")
 256
 257 /**
 258  * SWAP:
 259  *
 260  * In place exchange of two values
 261  */
 262 #define SWAP(a, b) \
 263     do { \
 264         (a) = (a) ^ (b); \
 265         (b) = (a) ^ (b); \
 266         (a) = (a) ^ (b); \
 267     } while (0)
 268
 269 /**
 270  * VIR_STEAL_PTR:
 271  *
 272  * Steals pointer passed as second argument into the first argument. Second
 273  * argument must not have side effects.
 274  */
 275 #define VIR_STEAL_PTR(a, b) \
 276     do { \
 277         (a) = (b); \
 278         (b) = NULL; \
 279     } while (0)
 280
 281 /**
 282  * VIR_RETURN_PTR:
 283  * @ret: pointer to return
 284  *
 285  * Returns value of @ret while clearing @ret. This ensures that pointers
 286  * freed by using VIR_AUTOPTR can be easily passed back to the caller without
 287  * any temporary variable. @ptr is evaluated more than once.
 288  */
 289 #define VIR_RETURN_PTR(ptr) \
 290     do { \
 291         typeof(ptr) virTemporaryReturnPointer = (ptr); \
 292         (ptr) = NULL; \
 293         return virTemporaryReturnPointer; \
 294     } while (0)
 295
 296 /**
 297  * virCheckFlags:
 298  * @supported: an OR'ed set of supported flags
 299  * @retval: return value in case unsupported flags were passed
 300  *
 301  * To avoid memory leaks this macro has to be used before any non-trivial
 302  * code which could possibly allocate some memory.
 303  *
 304  * Returns nothing. Exits the caller function if unsupported flags were
 305  * passed to it.
 306  */
 307 #define virCheckFlags(supported, retval) \
 308     do { \
 309         unsigned long __unsuppflags = flags & ~(supported); \
 310         if (__unsuppflags) { \
 311             virReportInvalidArg(flags, \
 312                                 _("unsupported flags (0x%lx) in function %s"), \
 313                                 __unsuppflags, __FUNCTION__); \
 314             return retval; \
 315         } \
 316     } while (0)
 317
 318 /**
 319  * virCheckFlagsGoto:
 320  * @supported: an OR'ed set of supported flags
 321  * @label: label to jump to on error
 322  *
 323  * To avoid memory leaks this macro has to be used before any non-trivial
 324  * code which could possibly allocate some memory.
 325  *
 326  * Returns nothing. Jumps to a label if unsupported flags were
 327  * passed to it.
 328  */
 329 #define virCheckFlagsGoto(supported, label) \
 330     do { \
 331         unsigned long __unsuppflags = flags & ~(supported); \
 332         if (__unsuppflags) { \
 333             virReportInvalidArg(flags, \
 334                                 _("unsupported flags (0x%lx) in function %s"), \
 335                                 __unsuppflags, __FUNCTION__); \
 336             goto label; \
 337         } \
 338     } while (0)
 339
 340 /* Macros to help dealing with mutually exclusive flags. */
 341
 342 /**
 343  * VIR_EXCLUSIVE_FLAGS_RET:
 344  *
 345  * @FLAG1: First flag to be checked.
 346  * @FLAG2: Second flag to be checked.
 347  * @RET: Return value.
 348  *
 349  * Reject mutually exclusive API flags.  The checked flags are compared
 350  * with flags variable.
 351  *
 352  * This helper does an early return and therefore it has to be called
 353  * before anything that would require cleanup.
 354  */
 355 #define VIR_EXCLUSIVE_FLAGS_RET(FLAG1, FLAG2, RET) \
 356     do { \
 357         if ((flags & FLAG1) && (flags & FLAG2)) { \
 358             virReportInvalidArg(ctl, \
 359                                 _("Flags '%s' and '%s' are mutually " \
 360                                   "exclusive"), \
 361                                 #FLAG1, #FLAG2); \
 362             return RET; \
 363         } \
 364     } while (0)
 365
 366 /**
 367  * VIR_EXCLUSIVE_FLAGS_GOTO:
 368  *
 369  * @FLAG1: First flag to be checked.
 370  * @FLAG2: Second flag to be checked.
 371  * @LABEL: Label to jump to.
 372  *
 373  * Reject mutually exclusive API flags.  The checked flags are compared
 374  * with flags variable.
 375  *
 376  * Returns nothing.  Jumps to a label if unsupported flags were
 377  * passed to it.
 378  */
 379 #define VIR_EXCLUSIVE_FLAGS_GOTO(FLAG1, FLAG2, LABEL) \
 380     do { \
 381         if ((flags & FLAG1) && (flags & FLAG2)) { \
 382             virReportInvalidArg(ctl, \
 383                                 _("Flags '%s' and '%s' are mutually " \
 384                                   "exclusive"), \
 385                                 #FLAG1, #FLAG2); \
 386             goto LABEL; \
 387         } \
 388     } while (0)
 389
 390 /* Macros to help dealing with flag requirements. */
 391
 392 /**
 393  * VIR_REQUIRE_FLAG_RET:
 394  *
 395  * @FLAG1: First flag to be checked.
 396  * @FLAG2: Second flag that is required by first flag.
 397  * @RET: Return value.
 398  *
 399  * Check whether required flag is set.  The checked flags are compared
 400  * with flags variable.
 401  *
 402  * This helper does an early return and therefore it has to be called
 403  * before anything that would require cleanup.
 404  */
 405 #define VIR_REQUIRE_FLAG_RET(FLAG1, FLAG2, RET) \
 406     do { \
 407         if ((flags & FLAG1) && !(flags & FLAG2)) { \
 408             virReportInvalidArg(ctl, \
 409                                 _("Flag '%s' is required by flag '%s'"), \
 410                                 #FLAG2, #FLAG1); \
 411             return RET; \
 412         } \
 413     } while (0)
 414
 415 /**
 416  * VIR_REQUIRE_FLAG_GOTO:
 417  *
 418  * @FLAG1: First flag to be checked.
 419  * @FLAG2: Second flag that is required by first flag.
 420  * @LABEL: Label to jump to.
 421  *
 422  * Check whether required flag is set.  The checked flags are compared
 423  * with flags variable.
 424  *
 425  * Returns nothing.  Jumps to a label if required flag is not set.
 426  */
 427 #define VIR_REQUIRE_FLAG_GOTO(FLAG1, FLAG2, LABEL) \
 428     do { \
 429         if ((flags & FLAG1) && !(flags & FLAG2)) { \
 430             virReportInvalidArg(ctl, \
 431                                 _("Flag '%s' is required by flag '%s'"), \
 432                                 #FLAG2, #FLAG1); \
 433             goto LABEL; \
 434         } \
 435     } while (0)
 436
 437 #define virCheckNonNullArgReturn(argname, retval) \
 438     do { \
 439         if (argname == NULL) { \
 440             virReportInvalidNonNullArg(argname); \
 441             return retval; \
 442         } \
 443     } while (0)
 444 #define virCheckNullArgGoto(argname, label) \
 445     do { \
 446         if (argname != NULL) { \
 447             virReportInvalidNullArg(argname); \
 448             goto label; \
 449         } \
 450     } while (0)
 451 #define virCheckNonNullArgGoto(argname, label) \
 452     do { \
 453         if (argname == NULL) { \
 454             virReportInvalidNonNullArg(argname); \
 455             goto label; \
 456         } \
 457     } while (0)
 458 #define virCheckNonEmptyStringArgGoto(argname, label) \
 459     do { \
 460         if (argname == NULL) { \
 461             virReportInvalidNonNullArg(argname); \
 462             goto label; \
 463         } \
 464         if (*argname == '\0') { \
 465             virReportInvalidEmptyStringArg(argname); \
 466             goto label; \
 467         } \
 468     } while (0)
 469 #define virCheckPositiveArgGoto(argname, label) \
 470     do { \
 471         if (argname <= 0) { \
 472             virReportInvalidPositiveArg(argname); \
 473             goto label; \
 474         } \
 475     } while (0)
 476 #define virCheckPositiveArgReturn(argname, retval) \
 477     do { \
 478         if (argname <= 0) { \
 479             virReportInvalidPositiveArg(argname); \
 480             return retval; \
 481         } \
 482     } while (0)
 483 #define virCheckNonZeroArgGoto(argname, label) \
 484     do { \
 485         if (argname == 0) { \
 486             virReportInvalidNonZeroArg(argname); \
 487             goto label; \
 488         } \
 489     } while (0)
 490 #define virCheckZeroArgGoto(argname, label) \
 491     do { \
 492         if (argname != 0) { \
 493             virReportInvalidNonZeroArg(argname); \
 494             goto label; \
 495         } \
 496     } while (0)
 497 #define virCheckNonNegativeArgGoto(argname, label) \
 498     do { \
 499         if (argname < 0) { \
 500             virReportInvalidNonNegativeArg(argname); \
 501             goto label; \
 502         } \
 503     } while (0)
 504 #define virCheckReadOnlyGoto(flags, label) \
 505     do { \
 506         if ((flags) & VIR_CONNECT_RO) { \
 507             virReportRestrictedError(_("read only access prevents %s"), \
 508                                      __FUNCTION__); \
 509             goto label; \
 510         } \
 511     } while (0)
 512
 513
 514
 515 /* divide value by size, rounding up */
 516 #define VIR_DIV_UP(value, size) (((value) + (size) - 1) / (size))
 517
 518 /* round up value to the closest multiple of size */
 519 #define VIR_ROUND_UP(value, size) (VIR_DIV_UP(value, size) * (size))
 520
 521 /* Round up to the next closest power of 2. It will return rounded number or 0
 522  * for 0 or number more than 2^31 (for 32bit unsigned int). */
 523 #define VIR_ROUND_UP_POWER_OF_TWO(value) \
 524     ((value) > 0 && (value) <= 1U << (sizeof(unsigned int) * 8 - 1) ? \
 525      1U << (sizeof(unsigned int) * 8 - count_leading_zeros((value) - 1)) : 0)
 526
 527
 528 /* Specific error values for use in forwarding programs such as
 529  * virt-login-shell; these values match what GNU env does.  */
 530 enum {
 531     EXIT_CANCELED = 125, /* Failed before attempting exec */
 532     EXIT_CANNOT_INVOKE = 126, /* Exists but couldn't exec */
 533     EXIT_ENOENT = 127, /* Could not find program to exec */
 534 };
 535
 536 #ifndef ENODATA
 537 # define ENODATA EIO
 538 #endif