14.4. Mapping an Image

download PDF
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.


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


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.
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.