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

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>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>
Signed-off-by: Peter Krempa <pkrempa@redhat.com>

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index dd534c10cb0c7e601df6bd1d8113c3287472e271..e28927ed6cbd573c7a75250d9b46b0b5eb69118e 100644 (file)
--- 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 case.
+
+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