Libvirt provides a portable, long term stable C API for managing the virtualization technologies provided by many operating systems. It includes support for QEMU, KVM, Xen, LXC, bhyve, Virtuozzo, VMware vCenter and ESX, VMware Desktop, Hyper-V, VirtualBox and the POWER Hypervisor.
Go to file
Laine Stump 85b22f528f util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT
I noticed when writing the backend functions for virNetworkUpdate that
I was repeating the same sequence of memmove, VIR_REALLOC, nXXX-- (and
messed up the args to memmove at least once), and had seen the same
sequence in a lot of other places, so I decided to write a few
utility functions/macros - see the .h file for full documentation.

The intent is to reduce the number of lines of code, but more
importantly to eliminate the need to check the element size and
element count arithmetic every time we need to do this (I *always*
make at least one mistake.)

VIR_INSERT_ELEMENT: insert one element at an arbitrary index within an
  array of objects. The size of each object is determined
  automatically by the macro using sizeof(*array). The new element's
  contents are copied into the inserted space, then the original copy
  of contents are 0'ed out (if everything else was
  successful). Compile-time assignment and size compatibility between
  the array and the new element is guaranteed (see explanation below
  [*])

VIR_INSERT_ELEMENT_COPY: identical to VIR_INSERT_ELEMENT, except that
  the original contents of newelem are not cleared to 0 (i.e. a copy
  is made).

VIR_APPEND_ELEMENT: This is just a special case of VIR_INSERT_ELEMENT
  that "inserts" one past the current last element.

VIR_APPEND_ELEMENT_COPY: identical to VIR_APPEND_ELEMENT, except that
  the original contents of newelem are not cleared to 0 (i.e. a copy
  is made).

VIR_DELETE_ELEMENT: delete one element at an arbitrary index within an
  array of objects. It's assumed that the element being deleted is
  already saved elsewhere (or cleared, if that's what is appropriate).

All five of these macros have an _INPLACE variant, which skips the
memory re-allocation of the array, assuming that the caller has
already done it (when inserting) or will do it later (when deleting).

Note that VIR_DELETE_ELEMENT* can return a failure, but only if an
invalid index is given (index + amount to delete is > current array
size), so in most cases you can safely ignore the return (that's why
the helper function virDeleteElementsN isn't declared with
ATTRIBUTE_RETURN_CHECK). A warning is logged if this ever happens,
since it is surely a coding error.

[*] One initial problem with the INSERT and APPEND macros was that,
due to both the array pointer and newelem pointer being cast to void*
when passing to virInsertElementsN(), any chance of type-checking was
lost. If we were going to move in newelem with a memmove anyway, we
would be no worse off for this. However, most current open-coded
insert/append operations use direct struct assignment to move the new
element into place (or just populate the new element directly) - thus
use of the new macros would open a possibility for new usage errors
that didn't exist before (e.g. accidentally sending &newelemptr rather
than newelemptr - I actually did this quite a lot in my test
conversions of existing code).

But thanks to Eric Blake's clever thinking, I was able to modify the
INSERT and APPEND macros so that they *do* check for both assignment
and size compatibility of *ptr (an element in the array) and newelem
(the element being copied into the new position of the array). This is
done via clever use of the C89-guaranteed fact that the sizeof()
operator must have *no* side effects (so an assignment inside sizeof()
is checked for validity, but not actually evaluated), and the fact
that virInsertElementsN has a "# of new elements" argument that we
want to always be 1.
2012-12-11 05:49:44 -05:00
.gnulib@d245e6ddd6 maint: update to latest gnulib 2012-10-22 20:25:44 -06:00
build-aux Document bracket whitespace rules & add syntax-check rule 2012-11-02 14:00:32 +00:00
daemon Inhibit daemon shutdown during driver initialization 2012-12-06 20:27:09 +01:00
docs qemu: Allow the user to specify vendor and product for disk 2012-12-07 16:53:27 +08:00
examples Bind connection close callback APIs to python binding 2012-12-04 13:50:11 +00:00
gnulib build: fix fresh checkout on RHEL5 2012-04-19 17:11:43 -06:00
include Add support for offline migration 2012-12-10 21:52:15 +01:00
m4 build: improve FORTIFY_SOURCE usage 2012-10-23 14:00:32 -06:00
po Add iSCSI backend storage driver for ESX 2012-12-03 21:12:23 +01:00
python Fix the indention 2012-12-04 23:41:35 +08:00
src util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT 2012-12-11 05:49:44 -05:00
tests qemu: Allow the user to specify vendor and product for disk 2012-12-07 16:53:27 +08:00
tools Add support for offline migration 2012-12-10 21:52:15 +01:00
.dir-locals.el build: avoid tabs that failed syntax-check 2012-09-06 09:43:46 -06:00
.gitignore Introduce APIs for splitting/joining strings 2012-11-30 20:05:43 +00:00
.gitmodules make .gnulib a submodule 2009-07-08 16:17:51 +02:00
.mailmap Autogenerate AUTHORS 2012-10-19 12:44:56 -04:00
AUTHORS.in Doug Goldstein gained commit capability 2012-11-15 09:34:01 +08:00
autobuild.sh Switch automated builds to use Mingw64 toolchain instead of Mingw32 2012-06-25 10:41:10 +01:00
autogen.sh build: fix incremental autogen.sh when no AUTHORS is present 2012-12-03 14:59:09 -07:00
bootstrap maint: regenerate bootstrap 2012-07-27 09:34:04 -06:00
bootstrap.conf build: prefer mkostemp for multi-thread safety 2012-10-31 10:06:10 -06:00
cfg.mk util: add VIR_(APPEND|INSERT|DELETE)_ELEMENT 2012-12-11 05:49:44 -05:00
ChangeLog-old virterror.c: Fix several spelling mistakes 2012-02-03 11:32:51 -07:00
configure.ac Convert libxl driver to Xen 4.2 2012-12-06 16:15:54 -07:00
COPYING.LIB remove all trailing blank lines 2009-07-16 15:06:42 +02:00
HACKING Document bracket whitespace rules & add syntax-check rule 2012-11-02 14:00:32 +00:00
libvirt.pc.in build: silence warning from autoconf 2012-05-30 09:22:02 -06:00
libvirt.spec.in Convert libxl driver to Xen 4.2 2012-12-06 16:15:54 -07:00
Makefile.am Autogenerate AUTHORS 2012-10-19 12:44:56 -04:00
Makefile.nonreentrant Ban use of all inet_* functions 2010-10-22 11:59:23 +01:00
mingw-libvirt.spec.in parallels: add driver skeleton 2012-08-01 11:44:26 +08:00
README Correct typos in the documentation (Atsushi SAKAI) 2008-01-24 10:15:13 +00:00
README-hacking maint: relax git minimum version 2010-02-24 14:29:27 -05:00
run.in syntax-check: fix run.in 2012-09-18 13:59:53 +02:00
TODO Update todo list file to point at bugzilla/website 2010-10-13 16:45:26 +01:00

         LibVirt : simple API for virtualization

  Libvirt is a C toolkit to interact with the virtualization capabilities
of recent versions of Linux (and other OSes). It is free software
available under the GNU Lesser General Public License. Virtualization of
the Linux Operating System means the ability to run multiple instances of
Operating Systems concurrently on a single hardware system where the basic
resources are driven by a Linux instance. The library aim at providing
long term stable C API initially for the Xen paravirtualization but
should be able to integrate other virtualization mechanisms if needed.

Daniel Veillard <veillard@redhat.com>