[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands i
From: |
Eric Blake |
Subject: |
Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation |
Date: |
Fri, 17 Aug 2018 15:59:40 -0500 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.9.1 |
On 08/17/2018 02:28 PM, Programmingkid wrote:
-o Used with a comma separated list of format specific options in
a
name=value format. Use "-o ?" for an overview of the options
Please spell that "-o help", not "-o ?". Otherwise, the user has to quote the
? to avoid it globbing into any single-byte file lying around in the current directory.
"-o ?" and "-o help" does not appear to work for this command. Maybe it should
be removed.
This is what I tried:
qemu-img amend -o help
qemu-img amend -o ?
The set of options depends on the file format being amended. So, you
have to try:
qemu-img amend -o help -f qcow2
or supply an image name, as in:
qemu-img amend -o help myimage.qcow2
(of course, the latter relies on image probing, which I just said is
potentially unsafe if you didn't use -f). But the point is the option
-o does work, just not in isolation.
-t Specifies the cache mode that should be used with the
destination file.
And what are those modes? If you're going to be wordy, then give the user
enough information to be useful. Otherwise, being terse in --help is fine (and
let the man page be wordy instead).
I don't know what the modes are. Anyone care to fill us in?
The source code is your friend. qemu-img.c has:
case 'T':
cache = optarg;
...
ret = bdrv_parse_cache_mode(cache, &flags, &writethrough);
then you search for bdrv_parse_cache_mode(), in block.c:
if (!strcmp(mode, "off") || !strcmp(mode, "none")) {
*writethrough = false;
*flags |= BDRV_O_NOCACHE;
} else if (!strcmp(mode, "directsync")) {
*writethrough = true;
*flags |= BDRV_O_NOCACHE;
} else if (!strcmp(mode, "writeback")) {
*writethrough = false;
} else if (!strcmp(mode, "unsafe")) {
*writethrough = false;
*flags |= BDRV_O_NO_FLUSH;
} else if (!strcmp(mode, "writethrough")) {
*writethrough = true;
So six different aliases, for five different modes. We can either
improve --help output to document these directly, or add a '-t help'
option (the way we have '-o help') to dynamically print the list.
Example:
qemu-img amend -o compat=0.10 -f qcow2 image.qcow2
Where's an example with --image-opts and --object secret?
I prefer examples that I think a user would actually use. The --image-opts and
-object options are not necessary to use this command.
Umm, they ARE necessary if you want to amend a LUKS-encrypted image, and
that IS something I would actually use. What's more, it's the complex
examples (like a LUKS-encrypted image) where seeing something spelled
out will save a LOT of hair-pulling from someone reading the docs (but,
alongside it should ALSO be a short-and-simple example).
We're trying to move away from compat=0.10 (also spelled compat=v2), and
instead start encouraging compat=v3.
So you want this: qemu-img amend -o compat=v3 -f qcow2 image.qcow2
Yes, that's one reasonable example, but should not be the only example.
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3266
Virtualization: qemu.org | libvirt.org
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Max Reitz, 2018/08/13
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Eric Blake, 2018/08/13
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Kevin Wolf, 2018/08/14
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Programmingkid, 2018/08/16
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Eric Blake, 2018/08/17
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Programmingkid, 2018/08/17
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation,
Eric Blake <=
- Re: [Qemu-block] [PATCH] qemu-img.c: increase spacing between commands in documentation, Programmingkid, 2018/08/18