libvirt-utils.h

   1 /*
   2  * libvirt-utils.h: misc helper APIs for python binding
   3  *
   4  * Copyright (C) 2013 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
  22 #ifndef __LIBVIRT_UTILS_H__
  23 # define __LIBVIRT_UTILS_H__
  24
  25 # define STREQ(a,b) (strcmp(a,b) == 0)
  26
  27 # ifndef MIN
  28 #  define MIN(a,b) (((a) < (b)) ? (a) : (b))
  29 # endif
  30
  31 /**
  32  * libvirt.h provides this as of version 1.2.0, but we want to be able
  33  * to support older versions of libvirt so copy and paste the macro from
  34  * libvirt.h
  35  */
  36 # ifndef LIBVIR_CHECK_VERSION
  37 #  define LIBVIR_CHECK_VERSION(major, minor, micro) \
  38     ((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)
  39 # endif
  40
  41 /* Return 1 if an array of N objects, each of size S, cannot exist due
  42    to size arithmetic overflow.  S must be positive and N must be
  43    nonnegative.  This is a macro, not a function, so that it
  44    works correctly even when SIZE_MAX < N.
  45
  46    By gnulib convention, SIZE_MAX represents overflow in size
  47    calculations, so the conservative dividend to use here is
  48    SIZE_MAX - 1, since SIZE_MAX might represent an overflowed value.
  49    However, malloc (SIZE_MAX) fails on all known hosts where
  50    sizeof (ptrdiff_t) <= sizeof (size_t), so do not bother to test for
  51    exactly-SIZE_MAX allocations on such hosts; this avoids a test and
  52    branch when S is known to be 1.  */
  53 # define xalloc_oversized(n, s) \
  54     ((size_t) (sizeof (ptrdiff_t) <= sizeof (size_t) ? -1 : -2) / (s) < (n))
  55
  56
  57 /* The __attribute__((__warn_unused_result__)) feature
  58    is available in gcc versions 3.4 and newer,
  59    while the typeof feature has been available since 2.7 at least.  */
  60 # if 3 < __GNUC__ + (4 <= __GNUC_MINOR__)
  61 #  define ignore_value(x) \
  62     (__extension__ ({ __typeof__ (x) __x = (x); (void) __x; }))
  63 # else
  64 #  define ignore_value(x) ((void) (x))
  65 # endif
  66
  67 # ifdef __GNUC__
  68
  69 #  ifndef __GNUC_PREREQ
  70 #   if defined __GNUC__ && defined __GNUC_MINOR__
  71 #    define __GNUC_PREREQ(maj, min)                                        \
  72     ((__GNUC__ << 16) + __GNUC_MINOR__ >= ((maj) << 16) + (min))
  73 #   else
  74 #    define __GNUC_PREREQ(maj, min) 0
  75 #   endif
  76 #  endif /* __GNUC_PREREQ */
  77
  78 /**
  79  * ATTRIBUTE_UNUSED:
  80  *
  81  * Macro to flag consciously unused parameters to functions
  82  */
  83 #  ifndef ATTRIBUTE_UNUSED
  84 #   define ATTRIBUTE_UNUSED __attribute__((__unused__))
  85 #  endif
  86
  87 /* gcc's handling of attribute nonnull is less than stellar - it does
  88  * NOT improve diagnostics, and merely allows gcc to optimize away
  89  * null code checks even when the caller manages to pass null in spite
  90  * of the attribute, leading to weird crashes.  Coverity, on the other
  91  * hand, knows how to do better static analysis based on knowing
  92  * whether a parameter is nonnull.  Make this attribute conditional
  93  * based on whether we are compiling for real or for analysis, while
  94  * still requiring correct gcc syntax when it is turned off.  See also
  95  * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=17308 */
  96 #  ifndef ATTRIBUTE_NONNULL
  97 #   if __GNUC_PREREQ (3, 3)
  98 #    if STATIC_ANALYSIS
  99 #     define ATTRIBUTE_NONNULL(m) __attribute__((__nonnull__(m)))
 100 #    else
 101 #     define ATTRIBUTE_NONNULL(m) __attribute__(())
 102 #    endif
 103 #   else
 104 #    define ATTRIBUTE_NONNULL(m)
 105 #   endif
 106 #  endif
 107
 108 #  ifndef ATTRIBUTE_RETURN_CHECK
 109 #   if __GNUC_PREREQ (3, 4)
 110 #    define ATTRIBUTE_RETURN_CHECK __attribute__((__warn_unused_result__))
 111 #   else
 112 #    define ATTRIBUTE_RETURN_CHECK
 113 #   endif
 114 #  endif
 115
 116 # else
 117 #  ifndef ATTRIBUTE_UNUSED
 118 #   define ATTRIBUTE_UNUSED
 119 #  endif
 120 #  ifndef ATTRIBUTE_NONNULL
 121 #   define ATTRIBUTE_NONNULL(m)
 122 #  endif
 123 #  ifndef ATTRIBUTE_RETURN_CHECK
 124 #   define ATTRIBUTE_RETURN_CHECK
 125 #  endif
 126 # endif                         /* __GNUC__ */
 127
 128
 129 /* Don't call these directly - use the macros below */
 130 int virAlloc(void *ptrptr, size_t size)
 131     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 132 int virAllocN(void *ptrptr, size_t size, size_t count)
 133     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 134 int virReallocN(void *ptrptr, size_t size, size_t count)
 135     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 136 void virFree(void *ptrptr) ATTRIBUTE_NONNULL(1);
 137
 138 /**
 139  * VIR_ALLOC:
 140  * @ptr: pointer to hold address of allocated memory
 141  *
 142  * Allocate sizeof(*ptr) bytes of memory and store
 143  * the address of allocated memory in 'ptr'. Fill the
 144  * newly allocated memory with zeros.
 145  *
 146  * This macro is safe to use on arguments with side effects.
 147  *
 148  * Returns -1 on failure (with OOM error reported), 0 on success
 149  */
 150 # define VIR_ALLOC(ptr) virAlloc(&(ptr), sizeof(*(ptr)))
 151
 152 /**
 153  * VIR_ALLOC_N:
 154  * @ptr: pointer to hold address of allocated memory
 155  * @count: number of elements to allocate
 156  *
 157  * Allocate an array of 'count' elements, each sizeof(*ptr)
 158  * bytes long and store the address of allocated memory in
 159  * 'ptr'. Fill the newly allocated memory with zeros.
 160  *
 161  * This macro is safe to use on arguments with side effects.
 162  *
 163  * Returns -1 on failure (with OOM error reported), 0 on success
 164  */
 165 # define VIR_ALLOC_N(ptr, count) virAllocN(&(ptr), sizeof(*(ptr)), (count))
 166
 167 /**
 168  * VIR_REALLOC_N:
 169  * @ptr: pointer to hold address of allocated memory
 170  * @count: number of elements to allocate
 171  *
 172  * Re-allocate an array of 'count' elements, each sizeof(*ptr)
 173  * bytes long and store the address of allocated memory in
 174  * 'ptr'. If 'ptr' grew, the added memory is uninitialized.
 175  *
 176  * This macro is safe to use on arguments with side effects.
 177  *
 178  * Returns -1 on failure (with OOM error reported), 0 on success
 179  */
 180 # define VIR_REALLOC_N(ptr, count) virReallocN(&(ptr), sizeof(*(ptr)), (count))
 181
 182 /**
 183  * VIR_FREE:
 184  * @ptr: pointer holding address to be freed
 185  *
 186  * Free the memory stored in 'ptr' and update to point
 187  * to NULL.
 188  *
 189  * This macro is safe to use on arguments with side effects.
 190  */
 191 # if !STATIC_ANALYSIS
 192 /* The ternary ensures that ptr is a pointer and not an integer type,
 193  * while evaluating ptr only once.  This gives us extra compiler
 194  * safety when compiling under gcc.  For now, we intentionally cast
 195  * away const, since a number of callers safely pass const char *.
 196  */
 197 #  define VIR_FREE(ptr) virFree((void *) (1 ? (const void *) &(ptr) : (ptr)))
 198 # else
 199 /* The Coverity static analyzer considers the else path of the "?:" and
 200  * flags the VIR_FREE() of the address of the address of memory as a
 201  * RESOURCE_LEAK resulting in numerous false positives (eg, VIR_FREE(&ptr))
 202  */
 203 #  define VIR_FREE(ptr) virFree((void *) &(ptr))
 204 # endif
 205
 206 /* Don't call this directly - use the macro below */
 207 int virFileClose(int *fdptr)
 208         ATTRIBUTE_RETURN_CHECK;
 209
 210 # define VIR_FORCE_CLOSE(FD) \
 211     ignore_value(virFileClose(&(FD)))
 212
 213 # if ! LIBVIR_CHECK_VERSION(1, 0, 2)
 214 void virTypedParamsClear(virTypedParameterPtr params, int nparams);
 215
 216 void virTypedParamsFree(virTypedParameterPtr params, int nparams);
 217 # endif /* ! LIBVIR_CHECK_VERSION(1, 0, 2) */
 218
 219 #endif /* __LIBVIRT_UTILS_H__ */