qemu-img: document 'info --backing-chain'

Signed-off-by: Kashyap Chamarthy <kashyap.cv@gmail.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index 0ef82e9ac7a89d607e1f2c8e38461cee5b438dba..a18136302d2ca7a7540672f1b9ef89603e89edc0 100644 (file)
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -34,9 +34,9 @@ STEXI
 ETEXI
 
 DEF("info", img_info,
 ETEXI
 
 DEF("info", img_info,

-    "info [-f fmt] [--output=ofmt] filename")
+    "info [-f fmt] [--output=ofmt] [--backing-chain] filename")

 STEXI
 STEXI

-@item info [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
+@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}

 ETEXI
 
 DEF("snapshot", img_snapshot,
 ETEXI
 
 DEF("snapshot", img_snapshot,

diff --git a/qemu-img.texi b/qemu-img.texi
index 42ec392c36d2e14fd39171295c92cfbf29d653a1..60b83fc11a458f4122af805a6f3541cfabd7d03e 100644 (file)
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -28,6 +28,10 @@ Command parameters:
 is the disk image format. It is guessed automatically in most cases. See below
 for a description of the supported disk formats.
 
 is the disk image format. It is guessed automatically in most cases. See below
 for a description of the supported disk formats.
 

+@item --backing-chain
+will enumerate information about backing files in a disk image chain. Refer
+below for further description.
+

 @item size
 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
 @item size
 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)


@@ -129,7 +133,7 @@ created as a copy on write image of the specified base image; the
 @var{backing_file} should have the same content as the input's base image,
 however the path, image format, etc may differ.
 
 @var{backing_file} should have the same content as the input's base image,
 however the path, image format, etc may differ.
 

-@item info [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
+@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}

 
 Give information about the disk image @var{filename}. Use it in
 particular to know the size reserved on disk which can be different
 
 Give information about the disk image @var{filename}. Use it in
 particular to know the size reserved on disk which can be different


@@ -137,6 +141,21 @@ from the displayed size. If VM snapshots are stored in the disk image,
 they are displayed too. The command can output in the format @var{ofmt}
 which is either @code{human} or @code{json}.
 
 they are displayed too. The command can output in the format @var{ofmt}
 which is either @code{human} or @code{json}.
 

+If a disk image has a backing file chain, information about each disk image in
+the chain can be recursively enumerated by using the option @code{--backing-chain}.
+
+For instance, if you have an image chain like:
+
+@example
+base.qcow2 <- snap1.qcow2 <- snap2.qcow2
+@end example
+
+To enumerate information about each disk image in the above chain, starting from top to base, do:
+
+@example
+qemu-img info --backing-chain snap2.qcow2
+@end example
+

 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
 
 List, apply, create or delete snapshots in image @var{filename}.
 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
 
 List, apply, create or delete snapshots in image @var{filename}.