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
This commit is contained in:
Ján Tomko 2015-02-20 12:25:42 +01:00
parent 52a166f493
commit c6807b507a
2 changed files with 20 additions and 3 deletions

View File

@ -8266,6 +8266,13 @@ virDomainAttachDeviceFlags(virDomainPtr domain,
* into S4 state (also known as hibernation) unless you also modify the * into S4 state (also known as hibernation) unless you also modify the
* persistent domain definition. * 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. * Returns 0 in case of success, -1 in case of failure.
*/ */
int int
@ -8341,6 +8348,13 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml)
* into S4 state (also known as hibernation) unless you also modify the * into S4 state (also known as hibernation) unless you also modify the
* persistent domain definition. * 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. * Returns 0 in case of success, -1 in case of failure.
*/ */
int int

View File

@ -2439,9 +2439,12 @@ as command B<attach-device>.
For passthrough host devices, see also B<nodedev-reattach>, needed if For passthrough host devices, see also B<nodedev-reattach>, needed if
the device does not use managed mode. the device does not use managed mode.
B<Note>: using of partial device definition XML files may lead to unexpected B<Note>: The supplied XML description of the device should be as specific
results as some fields may be autogenerated and thus match devices other than as its definition in the domain XML. The set of attributes used
expected. 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<--live> is specified, affect a running domain.
If I<--config> is specified, affect the next startup of a persistent domain. If I<--config> is specified, affect the next startup of a persistent domain.