domain: Document VIR_DOMAIN_XML_MIGRATABLE

Commit 28f8dfdc (1.0.0) added a flag to virDomainGetXMLDesc, but
failed to document its effects.  And considering that the
MIGRATABLE flag has been the source of past bugs (CVE-2014-7823,
fixed in commit b1674ad5 (1.2.11), or even cf2d4c60 (1.2.13) where
flag mismatch broke virsh edit), make the wording wishy-washy
enough to discourage using the flag casually, by mentioning that
the resulting XML is more for internal use than for validation
against the schema.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: John Ferlan <jferlan@redhat.com>
This commit is contained in:
Eric Blake 2019-02-13 17:07:32 -06:00
parent dafef600f4
commit 438ff36317

View File

@ -2561,6 +2561,15 @@ virDomainGetControlInfo(virDomainPtr domain,
* describing CPU capabilities is modified to match actual * describing CPU capabilities is modified to match actual
* capabilities of the host. * capabilities of the host.
* *
* If @flags contains VIR_DOMAIN_XML_MIGRATABLE, the XML is altered to
* assist in migrations, since the source and destination may be
* running different libvirt versions. This may include trimming
* redundant or default information that might confuse an older
* recipient, or exposing internal details that aid a newer recipient;
* this flag is rejected on read-only connections, and the resulting
* XML might not validate against the schema, so it is mainly for
* internal use.
*
* Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
* the caller must free() the returned value. * the caller must free() the returned value.
*/ */