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 # include <Python.h>
  26 # include <libvirt/libvirt.h>
  27
  28 # define STREQ(a,b) (strcmp(a,b) == 0)
  29
  30 # ifndef MIN
  31 #  define MIN(a,b) (((a) < (b)) ? (a) : (b))
  32 # endif
  33
  34 /**
  35  * libvirt.h provides this as of version 1.2.0, but we want to be able
  36  * to support older versions of libvirt so copy and paste the macro from
  37  * libvirt.h
  38  */
  39 # ifndef LIBVIR_CHECK_VERSION
  40 #  define LIBVIR_CHECK_VERSION(major, minor, micro) \
  41     ((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)
  42 # endif
  43
  44 /* Return 1 if an array of N objects, each of size S, cannot exist due
  45    to size arithmetic overflow.  S must be positive and N must be
  46    nonnegative.  This is a macro, not a function, so that it
  47    works correctly even when SIZE_MAX < N.
  48
  49    By gnulib convention, SIZE_MAX represents overflow in size
  50    calculations, so the conservative dividend to use here is
  51    SIZE_MAX - 1, since SIZE_MAX might represent an overflowed value.
  52    However, malloc (SIZE_MAX) fails on all known hosts where
  53    sizeof (ptrdiff_t) <= sizeof (size_t), so do not bother to test for
  54    exactly-SIZE_MAX allocations on such hosts; this avoids a test and
  55    branch when S is known to be 1.  */
  56 # define xalloc_oversized(n, s) \
  57     ((size_t) (sizeof (ptrdiff_t) <= sizeof (size_t) ? -1 : -2) / (s) < (n))
  58
  59
  60 /* The __attribute__((__warn_unused_result__)) feature
  61    is available in gcc versions 3.4 and newer,
  62    while the typeof feature has been available since 2.7 at least.  */
  63 # if 3 < __GNUC__ + (4 <= __GNUC_MINOR__)
  64 #  define ignore_value(x) \
  65     (__extension__ ({ __typeof__ (x) __x = (x); (void) __x; }))
  66 # else
  67 #  define ignore_value(x) ((void) (x))
  68 # endif
  69
  70 # ifdef __GNUC__
  71
  72 #  ifndef __GNUC_PREREQ
  73 #   if defined __GNUC__ && defined __GNUC_MINOR__
  74 #    define __GNUC_PREREQ(maj, min)                                        \
  75     ((__GNUC__ << 16) + __GNUC_MINOR__ >= ((maj) << 16) + (min))
  76 #   else
  77 #    define __GNUC_PREREQ(maj, min) 0
  78 #   endif
  79 #  endif /* __GNUC_PREREQ */
  80
  81 /**
  82  * ATTRIBUTE_UNUSED:
  83  *
  84  * Macro to flag consciously unused parameters to functions
  85  */
  86 #  ifndef ATTRIBUTE_UNUSED
  87 #   define ATTRIBUTE_UNUSED __attribute__((__unused__))
  88 #  endif
  89
  90 /* gcc's handling of attribute nonnull is less than stellar - it does
  91  * NOT improve diagnostics, and merely allows gcc to optimize away
  92  * null code checks even when the caller manages to pass null in spite
  93  * of the attribute, leading to weird crashes.  Coverity, on the other
  94  * hand, knows how to do better static analysis based on knowing
  95  * whether a parameter is nonnull.  Make this attribute conditional
  96  * based on whether we are compiling for real or for analysis, while
  97  * still requiring correct gcc syntax when it is turned off.  See also
  98  * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=17308 */
  99 #  ifndef ATTRIBUTE_NONNULL
 100 #   if __GNUC_PREREQ (3, 3)
 101 #    if STATIC_ANALYSIS
 102 #     define ATTRIBUTE_NONNULL(m) __attribute__((__nonnull__(m)))
 103 #    else
 104 #     define ATTRIBUTE_NONNULL(m) __attribute__(())
 105 #    endif
 106 #   else
 107 #    define ATTRIBUTE_NONNULL(m)
 108 #   endif
 109 #  endif
 110
 111 #  ifndef ATTRIBUTE_RETURN_CHECK
 112 #   if __GNUC_PREREQ (3, 4)
 113 #    define ATTRIBUTE_RETURN_CHECK __attribute__((__warn_unused_result__))
 114 #   else
 115 #    define ATTRIBUTE_RETURN_CHECK
 116 #   endif
 117 #  endif
 118
 119 # else
 120 #  ifndef ATTRIBUTE_UNUSED
 121 #   define ATTRIBUTE_UNUSED
 122 #  endif
 123 #  ifndef ATTRIBUTE_NONNULL
 124 #   define ATTRIBUTE_NONNULL(m)
 125 #  endif
 126 #  ifndef ATTRIBUTE_RETURN_CHECK
 127 #   define ATTRIBUTE_RETURN_CHECK
 128 #  endif
 129 # endif                         /* __GNUC__ */
 130
 131
 132 /* Don't call these directly - use the macros below */
 133 int virAlloc(void *ptrptr, size_t size)
 134     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 135 int virAllocN(void *ptrptr, size_t size, size_t count)
 136     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 137 int virReallocN(void *ptrptr, size_t size, size_t count)
 138     ATTRIBUTE_RETURN_CHECK ATTRIBUTE_NONNULL(1);
 139 void virFree(void *ptrptr) ATTRIBUTE_NONNULL(1);
 140
 141
 142 # if PY_MAJOR_VERSION > 2
 143 #  define libvirt_PyString_Check PyUnicode_Check
 144 # else
 145 #  define libvirt_PyString_Check PyString_Check
 146 # endif
 147
 148
 149 #define VIR_N_ELEMENTS(array) (sizeof(array) / sizeof(*(array)))
 150
 151 /* The two-statement sequence "Py_INCREF(Py_None); return Py_None;"
 152    is so common that we encapsulate it here.  Now, each use is simply
 153    return VIR_PY_NONE;  */
 154 #define VIR_PY_NONE (Py_INCREF (Py_None), Py_None)
 155 #define VIR_PY_INT_FAIL (libvirt_intWrap(-1))
 156 #define VIR_PY_INT_SUCCESS (libvirt_intWrap(0))
 157
 158
 159 /**
 160  * VIR_PY_TUPLE_SET_GOTO:
 161  * @TUPLE: a pointer to a tuple object
 162  * @INDEX: a position in the tuple object
 163  * @VALUE: a pointer to a python object to add into the tuple
 164  * @GOTO: a label to jump to in case of error
 165  *
 166  * Add the new value to specific place into the python tuple object.  In case of
 167  * error it will jump to provided label and DECREF the value to not leak memory.
 168  */
 169 #define VIR_PY_TUPLE_SET_GOTO(TUPLE, INDEX, VALUE, GOTO)                    \
 170     do {                                                                    \
 171         PyObject *tmpVal = VALUE;                                           \
 172         if (!tmpVal || PyTuple_SetItem(TUPLE, INDEX, tmpVal) < 0)           \
 173             goto GOTO;                                                      \
 174     } while (0)
 175
 176
 177 /**
 178  * VIR_PY_LIST_SET_GOTO:
 179  * @LIST: a pointer to a list object
 180  * @INDEX: a position in the list object
 181  * @VALUE: a pointer to a python object to add into the list
 182  * @GOTO: a label to jump to in case of error
 183  *
 184  * Add the new value to specific place into the python list object.  In case of
 185  * error it will jump to provided label and DECREF the value to not leak memory.
 186  */
 187 #define VIR_PY_LIST_SET_GOTO(LIST, INDEX, VALUE, GOTO)                      \
 188     do {                                                                    \
 189         PyObject *tmpVal = VALUE;                                           \
 190         if (!tmpVal || PyList_SetItem(LIST, INDEX, tmpVal) < 0)             \
 191             goto GOTO;                                                      \
 192     } while (0)
 193
 194
 195 /**
 196  * VIR_PY_LIST_APPEND_GOTO:
 197  * @LIST: a pointer to a python list object
 198  * @VALUE: a pointer to a python object to add into the list
 199  * @GOTO: a label to jump to in case of error
 200  *
 201  * Append the new value into the end of the python list object.  In case of
 202  * error it will jump to provided label and DECREF the value to not leak memory.
 203  */
 204 #define VIR_PY_LIST_APPEND_GOTO(LIST, VALUE, GOTO)                          \
 205     do {                                                                    \
 206         PyObject *tmpVal = VALUE;                                           \
 207         if (!tmpVal || PyList_Append(LIST, tmpVal) < 0) {                   \
 208             Py_XDECREF(tmpVal);                                             \
 209             goto GOTO;                                                      \
 210         }                                                                   \
 211         Py_DECREF(tmpVal);                                                  \
 212     } while (0)
 213
 214
 215 /**
 216  * VIR_PY_DICT_SET_GOTO:
 217  * @DICT: a pointer to a python dict object
 218  * @KEY: a pointer to a python string object which will be used as a key
 219  * @VALUE: a pointer to a python object to add into the dict under provided key
 220  * @GOTO: a label to jump to in case of error
 221  *
 222  * Add a new pair of key:value into the python dict object.  In case of error it
 223  * will jump to provided label.  It will DECREF both key and value in case of
 224  * success or error.
 225  */
 226 #define VIR_PY_DICT_SET_GOTO(DICT, KEY, VALUE, GOTO)                        \
 227     do {                                                                    \
 228         PyObject *tmpKey = KEY;                                             \
 229         PyObject *tmpVal = VALUE;                                           \
 230         if (!tmpKey || !tmpVal ||                                           \
 231             PyDict_SetItem(DICT, tmpKey, tmpVal) < 0) {                     \
 232             Py_XDECREF(tmpKey);                                             \
 233             Py_XDECREF(tmpVal);                                             \
 234             goto GOTO;                                                      \
 235         }                                                                   \
 236         Py_DECREF(tmpKey);                                                  \
 237         Py_DECREF(tmpVal);                                                  \
 238     } while (0)
 239
 240
 241 /**
 242  * VIR_ALLOC:
 243  * @ptr: pointer to hold address of allocated memory
 244  *
 245  * Allocate sizeof(*ptr) bytes of memory and store
 246  * the address of allocated memory in 'ptr'. Fill the
 247  * newly allocated memory with zeros.
 248  *
 249  * This macro is safe to use on arguments with side effects.
 250  *
 251  * Returns -1 on failure (with OOM error reported), 0 on success
 252  */
 253 # define VIR_ALLOC(ptr) virAlloc(&(ptr), sizeof(*(ptr)))
 254
 255 /**
 256  * VIR_ALLOC_N:
 257  * @ptr: pointer to hold address of allocated memory
 258  * @count: number of elements to allocate
 259  *
 260  * Allocate an array of 'count' elements, each sizeof(*ptr)
 261  * bytes long and store the address of allocated memory in
 262  * 'ptr'. Fill the newly allocated memory with zeros.
 263  *
 264  * This macro is safe to use on arguments with side effects.
 265  *
 266  * Returns -1 on failure (with OOM error reported), 0 on success
 267  */
 268 # define VIR_ALLOC_N(ptr, count) virAllocN(&(ptr), sizeof(*(ptr)), (count))
 269
 270 /**
 271  * VIR_REALLOC_N:
 272  * @ptr: pointer to hold address of allocated memory
 273  * @count: number of elements to allocate
 274  *
 275  * Re-allocate an array of 'count' elements, each sizeof(*ptr)
 276  * bytes long and store the address of allocated memory in
 277  * 'ptr'. If 'ptr' grew, the added memory is uninitialized.
 278  *
 279  * This macro is safe to use on arguments with side effects.
 280  *
 281  * Returns -1 on failure (with OOM error reported), 0 on success
 282  */
 283 # define VIR_REALLOC_N(ptr, count) virReallocN(&(ptr), sizeof(*(ptr)), (count))
 284
 285 /**
 286  * VIR_FREE:
 287  * @ptr: pointer holding address to be freed
 288  *
 289  * Free the memory stored in 'ptr' and update to point
 290  * to NULL.
 291  *
 292  * This macro is safe to use on arguments with side effects.
 293  */
 294 # if !STATIC_ANALYSIS
 295 /* The ternary ensures that ptr is a pointer and not an integer type,
 296  * while evaluating ptr only once.  This gives us extra compiler
 297  * safety when compiling under gcc.  For now, we intentionally cast
 298  * away const, since a number of callers safely pass const char *.
 299  */
 300 #  define VIR_FREE(ptr) virFree((void *) (1 ? (const void *) &(ptr) : (ptr)))
 301 # else
 302 /* The Coverity static analyzer considers the else path of the "?:" and
 303  * flags the VIR_FREE() of the address of the address of memory as a
 304  * RESOURCE_LEAK resulting in numerous false positives (eg, VIR_FREE(&ptr))
 305  */
 306 #  define VIR_FREE(ptr) virFree((void *) &(ptr))
 307 # endif
 308
 309 /* Don't call this directly - use the macro below */
 310 int virFileClose(int *fdptr)
 311         ATTRIBUTE_RETURN_CHECK;
 312
 313 # define VIR_FORCE_CLOSE(FD) \
 314     ignore_value(virFileClose(&(FD)))
 315
 316 # if ! LIBVIR_CHECK_VERSION(1, 0, 2)
 317 void virTypedParamsClear(virTypedParameterPtr params, int nparams);
 318
 319 void virTypedParamsFree(virTypedParameterPtr params, int nparams);
 320 # endif /* ! LIBVIR_CHECK_VERSION(1, 0, 2) */
 321
 322 PyObject * getPyVirTypedParameter(const virTypedParameter *params,
 323                                   int nparams);
 324 virTypedParameterPtr setPyVirTypedParameter(PyObject *info,
 325                                             const virTypedParameter *params,
 326                                             int nparams)
 327 ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2);
 328
 329
 330 # if LIBVIR_CHECK_VERSION(1, 1, 0)
 331 typedef struct {
 332     const char *name;
 333     int type;
 334 } virPyTypedParamsHint;
 335 typedef virPyTypedParamsHint *virPyTypedParamsHintPtr;
 336
 337
 338 int virPyDictToTypedPramaOne(virTypedParameterPtr *params,
 339                              int *n,
 340                              int *max,
 341                              virPyTypedParamsHintPtr hints,
 342                              int nhints,
 343                              const char *keystr,
 344                              PyObject *value);
 345 int virPyDictToTypedParams(PyObject *dict,
 346                            virTypedParameterPtr *ret_params,
 347                            int *ret_nparams,
 348                            virPyTypedParamsHintPtr hints,
 349                            int nhints)
 350 ATTRIBUTE_NONNULL(1) ATTRIBUTE_NONNULL(2) ATTRIBUTE_NONNULL(3);
 351 # endif /* LIBVIR_CHECK_VERSION(1, 1, 0) */
 352
 353 int virPyCpumapConvert(int cpunum,
 354                        PyObject *pycpumap,
 355                        unsigned char **cpumapptr,
 356                        int *cpumaplen);
 357
 358 #endif /* __LIBVIRT_UTILS_H__ */