[PATCH] docs: man: virsh: Document more carefully that 'guestinfo' can return nothing

Peter Krempa posted 1 patch 2 years, 2 months ago
Test syntax-check failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/cfa835bb1ca11b5a189d418076ee9bd0c67f5e7d.1642604804.git.pkrempa@redhat.com
docs/manpages/virsh.rst | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
[PATCH] docs: man: virsh: Document more carefully that 'guestinfo' can return nothing
Posted by Peter Krempa 2 years, 2 months ago
When invoking 'virsh guestinfo $VM' without explicitly specifying a
group of information to return, virsh always reports success even when
the guest agent doesn't report any information in the current state.
This is desired in situations when you are okay with stats being missing
and avoids spurious errors being reported.

Clarify that this is really desired in the man page.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2041665
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 docs/manpages/virsh.rst | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index dd534c10cb..19fb8cd0e4 100644
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -2768,11 +2768,14 @@ Note that this command requires a guest agent to be configured and running in
 the domain's guest OS.

 When run without any arguments, this command prints all information types that
-are supported by the guest agent. You can limit the types of information that
-are returned by specifying one or more flags.  If a requested information
-type is not supported, the processes will provide an exit code of 1.
-Available information types flags are *--user*, *--os*,
+are supported by the guest agent at that point, omitting unavailable ones.
+Success is always reported in this mode.
+
+You can limit the types of information that are returned by specifying one or
+more flags.  Available information types flags are *--user*, *--os*,
 *--timezone*, *--hostname*, *--filesystem*, *--disk* and *--interface*.
+If an explicitly requested information type is not supported by the guest agent
+at that point, the processes will provide an exit code of 1.

 Note that depending on the hypervisor type and the version of the guest agent
 running within the domain, not all of the following information may be
-- 
2.34.1

Re: [PATCH] docs: man: virsh: Document more carefully that 'guestinfo' can return nothing
Posted by Andrea Bolognani 2 years, 2 months ago
On Wed, Jan 19, 2022 at 04:06:44PM +0100, Peter Krempa wrote:
> +++ b/docs/manpages/virsh.rst
> @@ -2768,11 +2768,14 @@ Note that this command requires a guest agent to be configured and running in
>  the domain's guest OS.
>
>  When run without any arguments, this command prints all information types that
> -are supported by the guest agent. You can limit the types of information that
> -are returned by specifying one or more flags.  If a requested information
> -type is not supported, the processes will provide an exit code of 1.
> -Available information types flags are *--user*, *--os*,
> +are supported by the guest agent at that point, omitting unavailable ones.
> +Success is always reported in this mode.

Maybe s/mode/case/ ?

Either way

  Reviewed-by: Andrea Bolognani <abologna@redhat.com>

-- 
Andrea Bolognani / Red Hat / Virtualization