[libvirt PATCH] manpages/virsh: Clarify the meaning of the '--current' flag

Currently the documentation says: "If *--current* is specified, affect the current guest state." It's not entirely clear what states can "current" imply. E.g. `virsh detach-device --current [...]` — does this affect the live guest state or offline state? Answer: It affects the "current" state, which can either be live or offline. Spell that out; it's clearer that way. Fix all occurrences (i.e. as many as I could spot) of this. (Thanks: Dan Berrangé on IRC for clarifying.) Signed-off-by: Kashyap Chamarthy <kchamart(a)redhat.com&gt; --- For 'iothreadset', the documentation says: "If *--current* is specified or *--live* is not specified, then handle as if *--live* was specified." Does the above make sense? I don't know the implementation detail here. So I just added a parenthetical note on what the word "current" means. --- docs/manpages/virsh.rst | 84 ++++++++++++++++++++++++++--------------- 1 file changed, 54 insertions(+), 30 deletions(-) diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index 1a2cf09fb7..3c8d0434ab 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -1090,7 +1090,8 @@ reset the value back to the default. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. When setting the disk io parameters both *--live* and *--config* flags may be given, but *--current* is exclusive. For querying only one of *--live*, *--config* or *--current* can be specified. If no flag is specified, behavior @@ -1152,7 +1153,8 @@ any existing per-device write_bytes_sec for other devices remain unchanged. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -1986,7 +1988,8 @@ respectfully with average value of zero. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2089,7 +2092,8 @@ The *--live*, *--config*, and *--current* flags are only valid when using the *--period* option in order to set the collection period for the balloon driver. If *--live* is specified, only the running guest collection period is affected. If *--config* is specified, affect the next boot of a persistent -guest. If *--current* is specified, affect the current guest state. +guest. If *--current* is specified, affect the current guest state, +which can either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending @@ -2582,7 +2586,8 @@ See ``vcpupin`` for *cpulist*. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2746,7 +2751,7 @@ If *--live* is specified, affect a running guest. If the guest is not running an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. iothreaddel @@ -2767,7 +2772,7 @@ If *--live* is specified, affect a running guest. If the guest is not running an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. iothreadinfo @@ -2787,7 +2792,8 @@ the guest is not running, an error is returned. If *--config* is specified, get the IOThreads data from the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -then get the IOThread data based on the current guest state. +then get the IOThread data based on the current guest state, which can +either be live or offline. iothreadpin @@ -2814,7 +2820,7 @@ If *--live* is specified, affect a running guest. If the guest is not running, an error is returned. If *--config* is specified, affect the next boot of a persistent guest. If *--current* is specified or *--live* and *--config* are not specified, -affect the current guest state. +affect the current guest state, which can either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -2851,7 +2857,8 @@ next start, restore, etc. If *--live* is specified, affect a running guest. If the guest is not running an error is returned. If *--current* is specified or *--live* is not specified, then handle -as if *--live* was specified. +as if *--live* was specified. (Where "current" here means whatever the +present guest state is: live or offline.) managedsave @@ -2998,7 +3005,8 @@ For example, vSphere/ESX rounds the parameter up to mebibytes (1024 kibibytes). If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3393,7 +3401,8 @@ excluding a node. If *--live* is specified, set scheduler information of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. For running guests in Linux hosts, the changes made in the domain's numa parameters does not imply that the guest memory will be moved to a @@ -3486,7 +3495,8 @@ the *--perf* flag. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3715,7 +3725,8 @@ ESX (allocation scheduler): reservation, limit, shares If *--live* is specified, set scheduler information of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. ``Note``: The cpu_shares parameter has a valid value range of 0-262144; Negative values are wrapped to positive, and larger values are capped at the maximum. @@ -3957,7 +3968,8 @@ setmaxmem Change the maximum memory allocation limit for a guest domain. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -3988,7 +4000,8 @@ setmem Change the memory allocation for a guest domain. If *--live* is specified, perform a memory balloon of a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -4038,7 +4051,8 @@ specified together if supported by the hypervisor. If this command is run before the guest has finished booting, the guest may fail to process the change. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. When no flags are given, the *--live* flag is assumed and the guest domain must be active. In this situation it @@ -4084,9 +4098,9 @@ others. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. This is the -default. Both *--live* and *--config* flags may be given, but *--current* is -exclusive. +If *--current* is specified, affect the current domain state, which can +either be live or offline. This is the default. Both *--live* and +*--config* flags may be given, but *--current* is exclusive. shutdown @@ -4356,7 +4370,8 @@ also be allowed. The '-' denotes the range and the '^' denotes exclusive. For pinning the *vcpu* to all physical cpus specify 'r' as a *cpulist*. If *--live* is specified, affect a running guest. If *--config* is specified, affect the next boot of a persistent guest. -If *--current* is specified, affect the current guest state. +If *--current* is specified, affect the current guest state, which can +either be live or offline. Both *--live* and *--config* flags may be given if *cpulist* is present, but *--current* is exclusive. If no flag is specified, behavior is different depending on hypervisor. @@ -4411,7 +4426,8 @@ needed if the PCI device does not use managed mode. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4480,7 +4496,8 @@ is printed instead. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4568,7 +4585,8 @@ attached is printed instead. If ``--live`` is specified, affect a running domain. If ``--config`` is specified, affect the next startup of a persistent domain. -If ``--current`` is specified, affect the current domain state. +If ``--current`` is specified, affect the current domain state, which +can either be live or offline. Both ``--live`` and ``--config`` flags may be given, but ``--current`` is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4615,7 +4633,8 @@ returns. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4643,7 +4662,8 @@ removal of the device is notified asynchronously via libvirt events If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. @@ -4663,7 +4683,8 @@ from the domain. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4699,7 +4720,8 @@ present on the domain. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. When no flag is specified legacy API is used whose behavior depends on the hypervisor driver. @@ -4732,7 +4754,8 @@ libvirt XML format for a device. If *--live* is specified, affect a running domain. If *--config* is specified, affect the next startup of a persistent domain. -If *--current* is specified, affect the current domain state. +If *--current* is specified, affect the current domain state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. Not specifying any flag is the same as specifying *--current*. @@ -5223,7 +5246,8 @@ instance of <ip> will get the modification. If *--live* is specified, affect a running network. If *--config* is specified, affect the next startup of a persistent network. -If *--current* is specified, affect the current network state. +If *--current* is specified, affect the current network state, which can +either be live or offline. Both *--live* and *--config* flags may be given, but *--current* is exclusive. Not specifying any flag is the same as specifying *--current*. -- 2.26.2