2023-12-12 17:23:13 +01:00
|
|
|
HXCOMM See docs/devel/docs.rst for the format of this file.
|
|
|
|
HXCOMM
|
2017-08-03 18:33:50 +02:00
|
|
|
HXCOMM Keep the list of subcommands sorted by name.
|
2020-09-29 09:58:23 +02:00
|
|
|
HXCOMM Use DEFHEADING() to define headings in both help text and rST
|
2020-01-24 17:26:04 +01:00
|
|
|
HXCOMM Text between SRST and ERST are copied to rST version and
|
2009-06-07 01:42:17 +02:00
|
|
|
HXCOMM discarded from C version
|
|
|
|
HXCOMM DEF(command, callback, arg_string) is used to construct
|
|
|
|
HXCOMM command structures and help message.
|
2020-01-24 17:26:04 +01:00
|
|
|
HXCOMM HXCOMM can be used for comments, discarded from both rST and C
|
2009-06-07 01:42:17 +02:00
|
|
|
|
2020-01-24 17:26:04 +01:00
|
|
|
HXCOMM When amending the rST sections, please remember to copy the usage
|
2020-05-13 03:16:41 +02:00
|
|
|
HXCOMM over to the per-command sections in docs/tools/qemu-img.rst.
|
2018-05-04 00:56:48 +02:00
|
|
|
|
2017-08-03 18:33:50 +02:00
|
|
|
DEF("amend", img_amend,
|
2020-06-25 14:55:38 +02:00
|
|
|
"amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache] [--force] -o options filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2020-06-25 14:55:38 +02:00
|
|
|
.. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] [--force] -o OPTIONS FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2017-08-03 18:33:50 +02:00
|
|
|
|
2014-08-05 14:17:13 +02:00
|
|
|
DEF("bench", img_bench,
|
2020-02-05 17:30:08 +01:00
|
|
|
"bench [-c count] [-d depth] [-f fmt] [--flush-interval=flush_interval] [-i aio] [-n] [--no-drain] [-o offset] [--pattern=pattern] [-q] [-s buffer_size] [-S step_size] [-t cache] [-w] [-U] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2020-02-05 17:30:08 +01:00
|
|
|
.. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
qemu-img: Add bitmap sub-command
Include actions for --add, --remove, --clear, --enable, --disable, and
--merge (note that --clear is a bit of fluff, because the same can be
accomplished by removing a bitmap and then adding a new one in its
place, but it matches what QMP commands exist). Listing is omitted,
because it does not require a bitmap name and because it was already
possible with 'qemu-img info'. A single command line can play one or
more bitmap commands in sequence on the same bitmap name (although all
added bitmaps share the same granularity, and and all merged bitmaps
come from the same source file). Merge defaults to other bitmaps in
the primary image, but can also be told to merge bitmaps from a
distinct image.
While this supports --image-opts for the file being modified, I did
not think it worth the extra complexity to support that for the source
file in a cross-file merges. Likewise, I chose to have --merge only
take a single source rather than following the QMP support for
multiple merges in one go (although you can still use more than one
--merge in the command line); in part because qemu-img is offline and
therefore atomicity is not an issue.
Upcoming patches will add iotest coverage of these commands while
also testing other features.
Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Max Reitz <mreitz@redhat.com>
Message-Id: <20200513011648.166876-7-eblake@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
2020-05-13 03:16:45 +02:00
|
|
|
|
|
|
|
DEF("bitmap", img_bitmap,
|
|
|
|
"bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --disable)... [-b source_file [-F source_fmt]] [-g granularity] [--object objectdef] [--image-opts | -f fmt] filename bitmap")
|
|
|
|
SRST
|
|
|
|
.. option:: bitmap (--merge SOURCE | --add | --remove | --clear | --enable | --disable)... [-b SOURCE_FILE [-F SOURCE_FMT]] [-g GRANULARITY] [--object OBJECTDEF] [--image-opts | -f FMT] FILENAME BITMAP
|
|
|
|
ERST
|
|
|
|
|
2009-06-07 01:42:17 +02:00
|
|
|
DEF("check", img_check,
|
2018-05-04 00:56:44 +02:00
|
|
|
"check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
|
|
|
|
ERST
|
2009-06-07 01:42:17 +02:00
|
|
|
|
|
|
|
DEF("commit", img_commit,
|
2020-10-20 16:47:43 +02:00
|
|
|
"commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-r rate_limit] [-d] [-p] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2020-10-20 16:47:43 +02:00
|
|
|
.. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2009-06-07 01:42:17 +02:00
|
|
|
|
2013-02-13 09:09:41 +01:00
|
|
|
DEF("compare", img_compare,
|
2017-05-02 18:35:40 +02:00
|
|
|
"compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T src_cache] [-p] [-q] [-s] [-U] filename1 filename2")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
|
|
|
|
ERST
|
2013-02-13 09:09:41 +01:00
|
|
|
|
2009-06-07 01:42:17 +02:00
|
|
|
DEF("convert", img_convert,
|
2021-09-13 15:17:35 +02:00
|
|
|
"convert [--object objectdef] [--image-opts] [--target-image-opts] [--target-is-zero] [--bitmaps] [-U] [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-B backing_file [-F backing_fmt]] [-o options] [-l snapshot_param] [-S sparse_size] [-r rate_limit] [-m num_coroutines] [-W] [--salvage] filename [filename2 [...]] output_filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2021-09-21 16:28:12 +02:00
|
|
|
.. option:: convert [--object OBJECTDEF] [--image-opts] [--target-image-opts] [--target-is-zero] [--bitmaps] [-U] [-C] [-c] [-p] [-q] [-n] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-O OUTPUT_FMT] [-B BACKING_FILE [-F BACKING_FMT]] [-o OPTIONS] [-l SNAPSHOT_PARAM] [-S SPARSE_SIZE] [-r RATE_LIMIT] [-m NUM_COROUTINES] [-W] [--salvage] FILENAME [FILENAME2 [...]] OUTPUT_FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2009-06-07 01:42:17 +02:00
|
|
|
|
2017-08-03 18:33:50 +02:00
|
|
|
DEF("create", img_create,
|
qemu-img: Unify [-b [-F]] documentation
qemu-img convert documents the backing file and backing format options
as follows:
[-B backing_file [-F backing_fmt]]
whereas qemu-img create has this:
[-b backing_file] [-F backing_fmt]
That is, for convert, we document that -F cannot be given without -B,
while for create, way say that they are independent.
Indeed, it is technically possible to give -F without -b, because it is
left to the block driver to decide whether this is an error or not, so
sometimes it is:
$ qemu-img create -f qed -F qed test.qed 64M
Formatting 'test.qed', fmt=qed size=67108864 backing_fmt=qed [...]
And sometimes it is not:
$ qemu-img create -f qcow2 -F qcow2 test.qcow2 64M
Formatting 'test.qcow2', fmt=qcow2 cluster_size=65536 [...]
qemu-img: test.qcow2: Backing format cannot be used without backing file
Generally, it does not make much sense, though, and users should only
give -F with -b, so document it that way, as we have already done for
qemu-img convert (commit 1899bf47375ad40555dcdff12ba49b4b8b82df38).
Reported-by: Tingting Mao <timao@redhat.com>
Signed-off-by: Hanna Reitz <hreitz@redhat.com>
Message-Id: <20220131135908.32393-1-hreitz@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2022-01-31 14:59:08 +01:00
|
|
|
"create [--object objectdef] [-q] [-f fmt] [-b backing_file [-F backing_fmt]] [-u] [-o options] filename [size]")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
qemu-img: Unify [-b [-F]] documentation
qemu-img convert documents the backing file and backing format options
as follows:
[-B backing_file [-F backing_fmt]]
whereas qemu-img create has this:
[-b backing_file] [-F backing_fmt]
That is, for convert, we document that -F cannot be given without -B,
while for create, way say that they are independent.
Indeed, it is technically possible to give -F without -b, because it is
left to the block driver to decide whether this is an error or not, so
sometimes it is:
$ qemu-img create -f qed -F qed test.qed 64M
Formatting 'test.qed', fmt=qed size=67108864 backing_fmt=qed [...]
And sometimes it is not:
$ qemu-img create -f qcow2 -F qcow2 test.qcow2 64M
Formatting 'test.qcow2', fmt=qcow2 cluster_size=65536 [...]
qemu-img: test.qcow2: Backing format cannot be used without backing file
Generally, it does not make much sense, though, and users should only
give -F with -b, so document it that way, as we have already done for
qemu-img convert (commit 1899bf47375ad40555dcdff12ba49b4b8b82df38).
Reported-by: Tingting Mao <timao@redhat.com>
Signed-off-by: Hanna Reitz <hreitz@redhat.com>
Message-Id: <20220131135908.32393-1-hreitz@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2022-01-31 14:59:08 +01:00
|
|
|
.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE]
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2017-08-03 18:33:50 +02:00
|
|
|
|
2016-08-10 04:43:12 +02:00
|
|
|
DEF("dd", img_dd,
|
2017-05-02 18:35:40 +02:00
|
|
|
"dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=block_size] [count=blocks] [skip=blocks] if=input of=output")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
|
|
|
|
ERST
|
2016-08-10 04:43:12 +02:00
|
|
|
|
2009-06-07 01:42:17 +02:00
|
|
|
DEF("info", img_info,
|
2017-05-02 18:35:40 +02:00
|
|
|
"info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [--backing-chain] [-U] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME
|
|
|
|
ERST
|
2009-06-07 01:42:17 +02:00
|
|
|
|
2013-09-04 19:00:33 +02:00
|
|
|
DEF("map", img_map,
|
2020-05-13 15:36:29 +02:00
|
|
|
"map [--object objectdef] [--image-opts] [-f fmt] [--start-offset=offset] [--max-length=len] [--output=ofmt] [-U] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2020-05-13 15:36:29 +02:00
|
|
|
.. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2013-09-04 19:00:33 +02:00
|
|
|
|
2017-07-05 14:57:36 +02:00
|
|
|
DEF("measure", img_measure,
|
|
|
|
"measure [--output=ofmt] [-O output_fmt] [-o options] [--size N | [--object objectdef] [--image-opts] [-f fmt] [-l snapshot_param] filename]")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
|
|
|
|
ERST
|
2017-07-05 14:57:36 +02:00
|
|
|
|
2009-06-07 01:42:17 +02:00
|
|
|
DEF("snapshot", img_snapshot,
|
2017-05-02 18:35:40 +02:00
|
|
|
"snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a snapshot | -c snapshot | -d snapshot] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
|
|
|
|
ERST
|
2010-01-12 12:55:18 +01:00
|
|
|
|
|
|
|
DEF("rebase", img_rebase,
|
2023-09-19 18:58:03 +02:00
|
|
|
"rebase [--object objectdef] [--image-opts] [-U] [-q] [-f fmt] [-t cache] [-T src_cache] [-p] [-u] [-c] -b backing_file [-F backing_fmt] filename")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
2023-09-19 18:58:03 +02:00
|
|
|
.. option:: rebase [--object OBJECTDEF] [--image-opts] [-U] [-q] [-f FMT] [-t CACHE] [-T SRC_CACHE] [-p] [-u] [-c] -b BACKING_FILE [-F BACKING_FMT] FILENAME
|
2020-01-24 17:26:02 +01:00
|
|
|
ERST
|
2010-04-24 10:12:12 +02:00
|
|
|
|
|
|
|
DEF("resize", img_resize,
|
2018-05-04 00:56:47 +02:00
|
|
|
"resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size")
|
2020-01-24 17:26:02 +01:00
|
|
|
SRST
|
|
|
|
.. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
|
|
|
|
ERST
|