virConnectDomainXMLToNative: Add note about dynamically configured features

In the qemu driver certain configs such as disk throttling or CPU
hotplug is configured by interacting with the monitor at the startup
phase of the hypervisor and thus is not part of the "native config" as
returned by 'virConnectDomainXMLToNative'.

Similarly at least the commandline for qemu contains resources passed
via file descriptors which are obviously not part of the returned
"native config".

Add a paragraph into the documentation outlining that the native
configuration might not be completely usable.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>

diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index a32630a6e9be812fe32f32b6edc89252c85d7ea4..e3ced700b870bb1534cc9c2a77af88acb156fcde 100644 (file)
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -2909,6 +2909,13 @@ virConnectDomainXMLFromNative(virConnectPtr conn,
  * a native configuration file describing the domain.
  * The format of the native data is hypervisor dependent.
  *
+ * Note that certain hypervisor drivers such as the QEMU driver configure many
+ * aspects of the domain dynamically via hypervisor APIs and that may not be
+ * part of the returned native configuration format. Similarly certain resources
+ * are passed to the hypervisor via file descriptors, which are not part of the
+ * native configuration returned by this API. Such configuration is thus not
+ * trivially usable outside of libvirt.
+ *
  * Returns a 0 terminated UTF-8 encoded native config datafile, or
  * NULL in case of error. The caller must free() the returned value.
  *