docs, qapi: document qemu-img map

##

{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }

##

# @BlockDeviceMapEntry:

#

# Entry in the metadata map of the device (returned by "qemu-img map")

#

# @start: Offset in the image of the first byte described by this entry

#         (in bytes)

#

# @length: Length of the range described by this entry (in bytes)

#

# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.)

#         before reaching one for which the range is allocated.  The value is

#         in the range 0 to the depth of the image chain - 1.

#

# @zero: the sectors in this range read as zeros

#

# @data: reading the image will actually read data from a file (in particular,

#        if @offset is present this means that the sectors are not simply

#        preallocated, but contain actual data in raw format)

#

# @offset: if present, the image file stores the data for this range in

#          raw format at the given offset.

#

# Since 1.7

##

{ 'type': 'BlockDeviceMapEntry',

  'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool',

            'data': 'bool', '*offset': 'int' } }

##

# @BlockDirtyInfo:

#

qemu-img info --backing-chain snap2.qcow2

@end example

@item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}

Dump the metadata of image @var{filename} and its backing file chain.

In particular, this commands dumps the allocation state of every sector

of @var{filename}, together with the topmost file that allocates it in

the backing file chain.

Two option formats are possible.  The default format (@code{human})

only dumps known-nonzero areas of the file.  Known-zero parts of the

file are omitted altogether, and likewise for parts that are not allocated

throughout the chain.  @command{qemu-img} output will identify a file

from where the data can be read, and the offset in the file.  Each line

will include four fields, the first three of which are hexadecimal

numbers.  For example the first line of:

@example

Offset          Length          Mapped to       File

0               0x20000         0x50000         /tmp/overlay.qcow2

0x100000        0x10000         0x95380000      /tmp/backing.qcow2

@end example

@noindent

means that 0x20000 (131072) bytes starting at offset 0 in the image are

available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting

at offset 0x50000 (327680).  Data that is compressed, encrypted, or

otherwise not available in raw format will cause an error if @code{human}

format is in use.  Note that file names can include newlines, thus it is

not safe to parse this output format in scripts.

The alternative format @code{json} will return an array of dictionaries

in JSON format.  It will include similar information in

the @code{start}, @code{length}, @code{offset} fields;

it will also include other more specific information:

@itemize @minus

@item

whether the sectors contain actual data or not (boolean field @code{data};

if false, the sectors are either unallocated or stored as optimized

all-zero clusters);

@item

whether the data is known to read as zero (boolean field @code{zero});

@item

in order to make the output shorter, the target file is expressed as

a @code{depth}; for example, a depth of 2 refers to the backing file

of the backing file of @var{filename}.

@end itemize

In JSON format, the @code{offset} field is optional; it is absent in

cases where @code{human} format would omit the entry or exit with an error.

If @code{data} is false and the @code{offset} field is present, the

corresponding sectors in the file are not yet in use, but they are

preallocated.

For more information, consult @file{include/block/block.h} in QEMU's

source code.

@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}

List, apply, create or delete snapshots in image @var{filename}.