[libvirt] [PATCHv2] Clarify behavior or virDomainDetachDevice

Document that a complete device definition should be used and a partial match can lead to the device being detached. https://bugzilla.redhat.com/show_bug.cgi?id=872028 --- src/libvirt-domain.c | 14 ++++++++++++++ tools/virsh.pod | 9 ++++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 492e90a..fb85a28 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -8266,6 +8266,13 @@ virDomainAttachDeviceFlags(virDomainPtr domain, * into S4 state (also known as hibernation) unless you also modify the * persistent domain definition. * + * The supplied XML description of the device should be as specific + * as its definition in the domain XML. The set of attributes used + * to match the device are internal to the drivers. Using a partial definition, + * or attempting to detach a device that is not present in the domain XML, + * but shares some specific attributes with one that is present + * may lead to unexpected results. + * * Returns 0 in case of success, -1 in case of failure. */ int @@ -8341,6 +8348,13 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml) * into S4 state (also known as hibernation) unless you also modify the * persistent domain definition. * + * The supplied XML description of the device should be as specific + * as its definition in the domain XML. The set of attributes used + * to match the device are internal to the drivers. Using a partial definition, + * or attempting to detach a device that is not present in the domain XML, + * but shares some specific attributes with one that is present + * may lead to unexpected results. + * * Returns 0 in case of success, -1 in case of failure. */ int diff --git a/tools/virsh.pod b/tools/virsh.pod index 50de32c..09663f5 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -2439,9 +2439,12 @@ as command B<attach-device>. For passthrough host devices, see also B<nodedev-reattach>, needed if the device does not use managed mode. -B<Note>: using of partial device definition XML files may lead to unexpected -results as some fields may be autogenerated and thus match devices other than -expected. +B<Note>: The supplied XML description of the device should be as specific +as its definition in the domain XML. The set of attributes used +to match the device are internal to the drivers. Using a partial definition, +or attempting to detach a device that is not present in the domain XML, +but shares some specific attributes with one that is present +may lead to unexpected results. If I<--live> is specified, affect a running domain. If I<--config> is specified, affect the next startup of a persistent domain. -- 2.0.5