From c6807b507afce9c3483681bf24cc4a5260d29469 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A1n=20Tomko?= Date: Fri, 20 Feb 2015 12:25:42 +0100 Subject: [PATCH] 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 492e90af0e..89d1eab172 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 a7e0bb0293..343f26f2be 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -2439,9 +2439,12 @@ as command B. For passthrough host devices, see also B, needed if the device does not use managed mode. -B: 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: 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.