Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

14.4. Mapping an Image

Using the qemu-img map command, your can dump the metadata of the specified image file (imgname) and its backing file chain. The dump shows the allocation state of every sector in the (imgname) with the topmost file that allocates it in the backing file chain. Optionally, specify the file's format type (fmt). 
 # qemu-img map [-f fmt] [--output=fmt] imgname
There are two output formats, the human format and the json format:

14.4.1. The human Format

The default format (human) only dumps non-zero, allocated parts of the file. The output identifies a file from where data can be read and the offset in the file. Each line includes four fields. The following shows an example of an output: 
Offset          Length          Mapped to       File
0               0x20000         0x50000         /tmp/overlay.qcow2
0x100000        0x10000         0x95380000      /tmp/backing.qcow2
The first line means that 0x20000 (131072) bytes starting at offset 0 in the image are available in tmp/overlay.qcow2 (opened in raw format) starting at offset 0x50000 (327680). Data that is compressed, encrypted, or otherwise not available in raw format causes an error if human format is specified.

Note

File names can include newline characters. Therefore, it is not safe to parse output in human format in scripts.

14.4.2. The json Format

If the json option is specified, the output returns an array of dictionaries in JSON format. In addition to the information provided in the human option, the output includes the following information:
  • data - A Boolean field that shows whether or not the sectors contain data
  • zero - A Boolean field that shows whether or not the data is known to read as zero
  • depth - The depth of the backing file of filename

Note

When the json option is specified, the offset field is optional.
For more information about the qemu-img map command and additional options, see the relevant man page.