[PULL,20/24] qemu-img.texi: Describe human-readable info output

Commit Message

Kevin Wolf May 20, 2019, 4:14 p.m. UTC

From: Max Reitz <[e-mail]>

Ideally, it should be self-explanatory.  However, keys like "disk size"
arguably really are not self-explanatory.  In any case, there is no harm
in going into a some more detail here.

Signed-off-by: Max Reitz <[e-mail]>
Signed-off-by: Kevin Wolf <[e-mail]>
---
 qemu-img.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

Patch

diff --git a/qemu-img.texi b/qemu-img.texi
index 39562317ee..e8bc0fd7a2 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -428,6 +428,47 @@  The command can output in the format @var{ofmt} which is either @code{human} or
 @code{json}.  The JSON output is an object of QAPI type @code{ImageInfo}; with
 @code{--backing-chain}, it is an array of @code{ImageInfo} objects.
 
+@code{--output=human} reports the following information (for every image in the
+chain):
+@table @var
+@item image
+The image file name
+
+@item file format
+The image format
+
+@item virtual size
+The size of the guest disk
+
+@item disk size
+How much space the image file occupies on the host file system (may be shown as
+0 if this information is unavailable, e.g. because there is no file system)
+
+@item cluster_size
+Cluster size of the image format, if applicable
+
+@item encrypted
+Whether the image is encrypted (only present if so)
+
+@item cleanly shut down
+This is shown as @code{no} if the image is dirty and will have to be
+auto-repaired the next time it is opened in qemu.
+
+@item backing file
+The backing file name, if present
+
+@item backing file format
+The format of the backing file, if the image enforces it
+
+@item Snapshot list
+A list of all internal snapshots
+
+@item Format specific information
+Further information whose structure depends on the image format.  This section
+is a textual representation of the respective @code{ImageInfoSpecific*} QAPI
+object (e.g. @code{ImageInfoSpecificQCow2} for qcow2 images).
+@end table
+
 @item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename}
 
 Dump the metadata of image @var{filename} and its backing file chain.