Bug 1578259

Also, qemu-img uses different names for the same thing, for example:

$ qemu-img info test.qcow2 
image: test.qcow2
file format: qcow2
virtual size: 100G (107374182400 bytes)
disk size: 1.3M
cluster_size: 65536
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

$ qemu-img info test.qcow2 --output json
{
    "virtual-size": 107374182400,
    "filename": "test.qcow2",
    "cluster-size": 65536,
    "format": "qcow2",
    "actual-size": 1314816,
    "format-specific": {
        "type": "qcow2",
        "data": {
            "compat": "1.1",
            "lazy-refcounts": false,
            "refcount-bits": 16,
            "corrupt": false
        }
    },
    "dirty-flag": false
}

So we have:

--output human:
    image
    disk size
    cluster_size

--output json:
    filename
    actual-size
    cluster-size

Looking at qemu-img -h and man qemu-img, this seems to be a general issue with
the result format. Command line options and arguments are documented, but the format of the output is never documented. This is an issue for programs that want to use qemu-img json output.

Looks like this was added in this commit:

commit c054b3fd78f28b12f4d066583fc0ade017752479
Author: Benoît Canet <benoit>
Date:   Wed Sep 5 13:09:02 2012 +0200

    qemu-img: Add json output option to the info command.
    
    This option --output=[human|json] make qemu-img info output on
    human or JSON representation at the choice of the user.

In 4.1 with the commits 4db4390ef31648be28626dff51e87e3647485a46 and 987402c5c2c777cf3a1faf26f9a5a82f587bd3a4. Marking BZ as POST.

Hi,

The issue described in comment 2 continues to exists because (1) I think changing our output format may be a compatibility problem, and (2) I personally find “actual size” to be less intuitively meaningful than “disk size”.  But it’s clear that we cannot rename the JSON field, because that definitely would be a compatibility problem.  As for “filename” vs. “image”, I feel that’s just a result of --output=json and --output=human being useful for different consumers.  I think it would be weird for --output=human to report a “filename” (because the user would expect that to be exactly what they called qemu-img info with, which is not necessarily the case), but again, we cannot change --output=json.  (And I don’t see any problem for “file format” vs. “format” or “cluster_size” vs. “cluster-size”.)

As for actual-size, it isn’t documented in the man page because it has no place there.  What the man page does say is:

> The command can output in the format ofmt which is either "human" or "json".  The JSON output is an object of QAPI type "ImageInfo"; with "--backing-chain", it is an array of "ImageInfo" objects.

And the ImageInfo QAPI type is documented in the QAPI/QMP documentation (qemu-qmp-ref.7).


(The --output=human fields are documented in the man page, because there is no other place where we already document them; with the exception of “format specific information”, which again references the QAPI documentation.)


Thanks,

Max

Thanks Max a lot, I can find the info now. And set this bug as verified accordingly.


Tested with:
qemu-kvm-4.1.0-10.module+el8.1.0+4234+33aa4f57


Get content 'actual-size' in the doc file:
# cat /usr/share/doc/qemu-kvm/qemu-qmp-ref.txt | grep "actual-size" -A 2 
     'actual-size: int' (optional)
          actual size on disk in bytes of the image
     'dirty-flag: boolean' (optional)

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2019:3723