mirrors/qemu
0
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2024-12-14 15:03:33 +08:00
Code Issues Packages Projects Releases Wiki Activity
b603136402
qemu/qemu-img-cmds.hx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

103 lines
5.6 KiB
Haxe
Raw Normal View History

docs/devel/docs: Document .hx file syntax We don't currently document the syntax of .hx files anywhere except in a few comments at the top of individual .hx files. We don't even have somewhere in the developer docs where we could do this. Add a new files docs/devel/docs.rst which can be a place to document how our docs build process works. For the moment, put in only a brief introductory paragraph and the documentation of the .hx files. We could later add to this file by for example describing how the QAPI-schema-to-docs process works, or anything else that developers might need to know about how to add documentation. Make the .hx files refer to this doc file, and clean up their header comments to be more accurate for the usage in each file and less cut-n-pasted. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Luc Michel <luc.michel@amd.com> Reviewed-by: David Woodhouse <dwmw@amazon.co.uk> Message-id: 20231212162313.1742462-1-peter.maydell@linaro.org
2023-12-13 00:23:13 +08:00
HXCOMM See docs/devel/docs.rst for the format of this file.
HXCOMM
qemu-img: Sort sub-command names in --help 'amend' and 'create' were not listed alphabetically; hoist them earlier. Separate the @end table block to make it easier to copy-and-paste the addition of future sub-commands. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20170803163353.19558-2-eblake@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-08-04 00:33:50 +08:00
HXCOMM Keep the list of subcommands sorted by name.
qemu-img-cmds.hx: Update comment that mentions Texinfo Missed in 3c95fdef94 "Update comments in .hx files that mention Texinfo". Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20200929075824.1517969-2-armbru@redhat.com> Signed-off-by: Laurent Vivier <laurent@vivier.eu>
2020-09-29 15:58:23 +08:00
HXCOMM Use DEFHEADING() to define headings in both help text and rST
qemu-img-cmds.hx: Remove texinfo document fragments Now the qemu-img documentation has been converted to rST, we can remove the texinfo document fragments from qemu-img-cmds.hx, as they are no longer used. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-7-peter.maydell@linaro.org
2020-01-25 00:26:04 +08:00
HXCOMM Text between SRST and ERST are copied to rST version and
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
HXCOMM discarded from C version
HXCOMM DEF(command, callback, arg_string) is used to construct
HXCOMM command structures and help message.
qemu-img-cmds.hx: Remove texinfo document fragments Now the qemu-img documentation has been converted to rST, we can remove the texinfo document fragments from qemu-img-cmds.hx, as they are no longer used. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-7-peter.maydell@linaro.org
2020-01-25 00:26:04 +08:00
HXCOMM HXCOMM can be used for comments, discarded from both rST and C
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
qemu-img-cmds.hx: Remove texinfo document fragments Now the qemu-img documentation has been converted to rST, we can remove the texinfo document fragments from qemu-img-cmds.hx, as they are no longer used. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20200124162606.8787-7-peter.maydell@linaro.org
2020-01-25 00:26:04 +08:00
HXCOMM When amending the rST sections, please remember to copy the usage
qemu-img: Fix stale comments on doc location Missed in commit e13c59fa. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Max Reitz <mreitz@redhat.com> Message-Id: <20200513011648.166876-3-eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
2020-05-13 09:16:41 +08:00
HXCOMM over to the per-command sections in docs/tools/qemu-img.rst.
qemu-img-cmds.hx: add passive-aggressive note I'm kidding. It's very easy to forget there are per-command sections in the texi, and insane that we don't autogenerate those, too. Until then, leave a little post-it note in this .hx file until I find a way to delete it. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Jeff Cody <jcody@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2018-05-04 06:56:48 +08:00
qemu-img: Sort sub-command names in --help 'amend' and 'create' were not listed alphabetically; hoist them earlier. Separate the @end table block to make it easier to copy-and-paste the addition of future sub-commands. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20170803163353.19558-2-eblake@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-08-04 00:33:50 +08:00
DEF("amend", img_amend,
block/amend: add 'force' option 'force' option will be used for some unsafe amend operations. This includes things like erasing last keyslot in luks based formats (which destroys the data, unless the master key is backed up by external means), but that _might_ be desired result. Signed-off-by: Maxim Levitsky <mlevitsk@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Max Reitz <mreitz@redhat.com> Message-Id: <20200608094030.670121-4-mlevitsk@redhat.com> Signed-off-by: Max Reitz <mreitz@redhat.com>
2020-06-25 20:55:38 +08:00
"amend [--object objectdef] [--image-opts] [-p] [-q] [-f fmt] [-t cache] [--force] -o options filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
block/amend: add 'force' option 'force' option will be used for some unsafe amend operations. This includes things like erasing last keyslot in luks based formats (which destroys the data, unless the master key is backed up by external means), but that _might_ be desired result. Signed-off-by: Maxim Levitsky <mlevitsk@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Max Reitz <mreitz@redhat.com> Message-Id: <20200608094030.670121-4-mlevitsk@redhat.com> Signed-off-by: Max Reitz <mreitz@redhat.com>
2020-06-25 20:55:38 +08:00
.. option:: amend [--object OBJECTDEF] [--image-opts] [-p] [-q] [-f FMT] [-t CACHE] [--force] -o OPTIONS FILENAME
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
qemu-img: Sort sub-command names in --help 'amend' and 'create' were not listed alphabetically; hoist them earlier. Separate the @end table block to make it easier to copy-and-paste the addition of future sub-commands. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20170803163353.19558-2-eblake@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-08-04 00:33:50 +08:00
qemu-img bench This adds a qemu-img command that allows doing some simple benchmarks for the block layer without involving guest devices and a real VM. For the start, this implements only a test of sequential reads. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Denis V. Lunev <den@openvz.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
2014-08-05 20:17:13 +08:00
DEF("bench", img_bench,
qemu-img: Place the '-i aio' option in alphabetical order The '-i AIO' option was accidentally placed after '-n' and '-t'. Move it after '--flush-interval'. Signed-off-by: Julia Suvorova <jusual@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-Id: <20200205163008.204493-1-jusual@redhat.com> Signed-off-by: Laurent Vivier <laurent@vivier.eu>
2020-02-06 00:30:08 +08: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")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
qemu-img: Place the '-i aio' option in alphabetical order The '-i AIO' option was accidentally placed after '-n' and '-t'. Move it after '--flush-interval'. Signed-off-by: Julia Suvorova <jusual@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-Id: <20200205163008.204493-1-jusual@redhat.com> Signed-off-by: Laurent Vivier <laurent@vivier.eu>
2020-02-06 00:30:08 +08: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
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08: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 09:16:45 +08: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
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
DEF("check", img_check,
qemu-img-commands.hx: argument ordering fixups The TEXI and string versions are actually identical, except for markup. We can probably automate this... but make the ordering the same until then. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Jeff Cody <jcody@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2018-05-04 06:56:44 +08:00
"check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: check [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [--output=OFMT] [-r [leaks | all]] [-T SRC_CACHE] [-U] FILENAME
ERST
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
DEF("commit", img_commit,
qemu-img: add support for rate limit in qemu-img commit add support for rate limit in qemu-img commit. Signed-off-by: Zhengui <lizhengui@huawei.com> Message-Id: <1603205264-17424-2-git-send-email-lizhengui@huawei.com> Reviewed-by: Alberto Garcia <berto@igalia.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2020-10-20 22:47:43 +08:00
"commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-r rate_limit] [-d] [-p] filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
qemu-img: add support for rate limit in qemu-img commit add support for rate limit in qemu-img commit. Signed-off-by: Zhengui <lizhengui@huawei.com> Message-Id: <1603205264-17424-2-git-send-email-lizhengui@huawei.com> Reviewed-by: Alberto Garcia <berto@igalia.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2020-10-20 22:47:43 +08:00
.. option:: commit [--object OBJECTDEF] [--image-opts] [-q] [-f FMT] [-t CACHE] [-b BASE] [-r RATE_LIMIT] [-d] [-p] FILENAME
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
qemu-img: Add compare subcommand This patch adds new qemu-img subcommand that compares content of two disk images. Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com> Reviewed-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2013-02-13 16:09:41 +08:00
DEF("compare", img_compare,
qemu-img: Update documentation for -U Signed-off-by: Fam Zheng <famz@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2017-05-03 00:35:40 +08:00
"compare [--object objectdef] [--image-opts] [-f fmt] [-F fmt] [-T src_cache] [-p] [-q] [-s] [-U] filename1 filename2")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: compare [--object OBJECTDEF] [--image-opts] [-f FMT] [-F FMT] [-T SRC_CACHE] [-p] [-q] [-s] [-U] FILENAME1 FILENAME2
ERST
qemu-img: Add compare subcommand This patch adds new qemu-img subcommand that compares content of two disk images. Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com> Reviewed-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2013-02-13 16:09:41 +08:00
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
DEF("convert", img_convert,
qemu-img: Add -F shorthand to convert Although we have long supported 'qemu-img convert -o backing_file=foo,backing_fmt=bar', the fact that we have a shortcut -B for backing_file but none for backing_fmt has made it more likely that users accidentally run into: qemu-img: warning: Deprecated use of backing file without explicit backing format when using -B instead of -o. For similarity with other qemu-img commands, such as create and compare, add '-F $fmt' as the shorthand for '-o backing_fmt=$fmt'. Update iotest 122 for coverage of both spellings. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20210913131735.1948339-1-eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Reviewed-by: Maxim Levitsky <mlevitsk@redhat.com> Signed-off-by: Hanna Reitz <hreitz@redhat.com>
2021-09-13 21:17:35 +08: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")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
qemu-img: Consistent docs for convert -F Use consistent capitalization, and fix a missed line (we duplicate the qemu-img synopses in too many places). Fixes: 1899bf4737 (qemu-img: Add -F shorthand to convert) Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20210921142812.2631605-1-eblake@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Signed-off-by: Hanna Reitz <hreitz@redhat.com>
2021-09-21 22:28:12 +08: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
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
qemu-img: Sort sub-command names in --help 'amend' and 'create' were not listed alphabetically; hoist them earlier. Separate the @end table block to make it easier to copy-and-paste the addition of future sub-commands. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20170803163353.19558-2-eblake@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-08-04 00:33:50 +08: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 21:59:08 +08:00
"create [--object objectdef] [-q] [-f fmt] [-b backing_file [-F backing_fmt]] [-u] [-o options] filename [size]")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08: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 21:59:08 +08:00
.. option:: create [--object OBJECTDEF] [-q] [-f FMT] [-b BACKING_FILE [-F BACKING_FMT]] [-u] [-o OPTIONS] FILENAME [SIZE]
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
qemu-img: Sort sub-command names in --help 'amend' and 'create' were not listed alphabetically; hoist them earlier. Separate the @end table block to make it easier to copy-and-paste the addition of future sub-commands. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20170803163353.19558-2-eblake@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2017-08-04 00:33:50 +08:00
qemu-img: add the 'dd' subcommand This patch adds a basic dd subcommand analogous to dd(1) to qemu-img. For the start, this implements the bs, if, of and count options and requires both if and of to be specified (no stdin/stdout if not specified) and doesn't support tty, pipes, etc. The image format must be specified with -O for the output if the raw format is not the intended one. Two tests are added to test qemu-img dd. Signed-off-by: Reda Sallahi <fullmanet@gmail.com> Message-id: 20160810024312.14544-1-fullmanet@gmail.com Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> [mreitz: Moved test 158 to 170] Signed-off-by: Max Reitz <mreitz@redhat.com>
2016-08-10 10:43:12 +08:00
DEF("dd", img_dd,
qemu-img: Update documentation for -U Signed-off-by: Fam Zheng <famz@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2017-05-03 00:35:40 +08:00
"dd [--image-opts] [-U] [-f fmt] [-O output_fmt] [bs=block_size] [count=blocks] [skip=blocks] if=input of=output")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: dd [--image-opts] [-U] [-f FMT] [-O OUTPUT_FMT] [bs=BLOCK_SIZE] [count=BLOCKS] [skip=BLOCKS] if=INPUT of=OUTPUT
ERST
qemu-img: add the 'dd' subcommand This patch adds a basic dd subcommand analogous to dd(1) to qemu-img. For the start, this implements the bs, if, of and count options and requires both if and of to be specified (no stdin/stdout if not specified) and doesn't support tty, pipes, etc. The image format must be specified with -O for the output if the raw format is not the intended one. Two tests are added to test qemu-img dd. Signed-off-by: Reda Sallahi <fullmanet@gmail.com> Message-id: 20160810024312.14544-1-fullmanet@gmail.com Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> [mreitz: Moved test 158 to 170] Signed-off-by: Max Reitz <mreitz@redhat.com>
2016-08-10 10:43:12 +08:00
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
DEF("info", img_info,
qemu-img: Update documentation for -U Signed-off-by: Fam Zheng <famz@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2017-05-03 00:35:40 +08:00
"info [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [--backing-chain] [-U] filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: info [--object OBJECTDEF] [--image-opts] [-f FMT] [--output=OFMT] [--backing-chain] [-U] FILENAME
ERST
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
qemu-img: add a "map" subcommand This command dumps the metadata of an entire chain, in either tabular or JSON format. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2013-09-05 01:00:33 +08:00
DEF("map", img_map,
qemu-img: Add --start-offset and --max-length to map The mapping operation of large disks especially ones stored over a long chain of QCOW2 files can take a long time to finish. Additionally when mapping fails there was no way recover by restarting the mapping from the failed location. The new options, --start-offset and --max-length allows the user to divide these type of map operations into shorter independent tasks. Reviewed-by: Eric Blake <eblake@redhat.com> Acked-by: Mark Kanda <mark.kanda@oracle.com> Co-developed-by: Yoav Elnekave <yoav.elnekave@oracle.com> Signed-off-by: Yoav Elnekave <yoav.elnekave@oracle.com> Signed-off-by: Eyal Moscovici <eyal.moscovici@oracle.com> Message-Id: <20200513133629.18508-5-eyal.moscovici@oracle.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2020-05-13 21:36:29 +08:00
"map [--object objectdef] [--image-opts] [-f fmt] [--start-offset=offset] [--max-length=len] [--output=ofmt] [-U] filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
qemu-img: Add --start-offset and --max-length to map The mapping operation of large disks especially ones stored over a long chain of QCOW2 files can take a long time to finish. Additionally when mapping fails there was no way recover by restarting the mapping from the failed location. The new options, --start-offset and --max-length allows the user to divide these type of map operations into shorter independent tasks. Reviewed-by: Eric Blake <eblake@redhat.com> Acked-by: Mark Kanda <mark.kanda@oracle.com> Co-developed-by: Yoav Elnekave <yoav.elnekave@oracle.com> Signed-off-by: Yoav Elnekave <yoav.elnekave@oracle.com> Signed-off-by: Eyal Moscovici <eyal.moscovici@oracle.com> Message-Id: <20200513133629.18508-5-eyal.moscovici@oracle.com> Signed-off-by: Eric Blake <eblake@redhat.com>
2020-05-13 21:36:29 +08:00
.. option:: map [--object OBJECTDEF] [--image-opts] [-f FMT] [--start-offset=OFFSET] [--max-length=LEN] [--output=OFMT] [-U] FILENAME
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
qemu-img: add a "map" subcommand This command dumps the metadata of an entire chain, in either tabular or JSON format. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2013-09-05 01:00:33 +08:00
qemu-img: add measure subcommand The measure subcommand calculates the size required by a new image file. This can be used by users or management tools that need to allocate space on an LVM volume, SAN LUN, etc before creating or converting an image file. Suggested-by: Maor Lipchuk <mlipchuk@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Alberto Garcia <berto@igalia.com> Message-id: 20170705125738.8777-8-stefanha@redhat.com Signed-off-by: Max Reitz <mreitz@redhat.com>
2017-07-05 20:57:36 +08: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]")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: measure [--output=OFMT] [-O OUTPUT_FMT] [-o OPTIONS] [--size N | [--object OBJECTDEF] [--image-opts] [-f FMT] [-l SNAPSHOT_PARAM] FILENAME]
ERST
qemu-img: add measure subcommand The measure subcommand calculates the size required by a new image file. This can be used by users or management tools that need to allocate space on an LVM volume, SAN LUN, etc before creating or converting an image file. Suggested-by: Maor Lipchuk <mlipchuk@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Alberto Garcia <berto@igalia.com> Message-id: 20170705125738.8777-8-stefanha@redhat.com Signed-off-by: Max Reitz <mreitz@redhat.com>
2017-07-05 20:57:36 +08:00
Use hxtool for qemu-img command list Use hxtool to generate the 'command syntax' section of qemu-img's help message, and the corresponding section of the texinfo documentation. This has the side-effect of adding 'check' to this list of commands in the texinfo documentation. Signed-off-by: Stuart Brady <stuart.brady@gmail.com>
2009-06-07 07:42:17 +08:00
DEF("snapshot", img_snapshot,
qemu-img: Update documentation for -U Signed-off-by: Fam Zheng <famz@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2017-05-03 00:35:40 +08:00
"snapshot [--object objectdef] [--image-opts] [-U] [-q] [-l | -a snapshot | -c snapshot | -d snapshot] filename")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: snapshot [--object OBJECTDEF] [--image-opts] [-U] [-q] [-l | -a SNAPSHOT | -c SNAPSHOT | -d SNAPSHOT] FILENAME
ERST
qemu-img rebase This adds a rebase subcommand to qemu-img which allows to change the backing file of an image. In default mode, both the current and the new backing file need to exist, and after the rebase, the COW image is guaranteed to have the same guest visible content as before. To achieve this, old and new backing file are compared and, if necessary, data is copied from the old backing file into the COW image. With -u an unsafe mode is enabled that doesn't require the backing files to exist. It merely changes the backing file reference in the COW image. This is useful for renaming or moving the backing file. The user is responsible to make sure that the new backing file has no changes compared to the old one, or corruption may occur. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>
2010-01-12 19:55:18 +08:00
DEF("rebase", img_rebase,
qemu-img: add compression option to rebase subcommand If we rebase an image whose backing file has compressed clusters, we might end up wasting disk space since the copied clusters are now uncompressed. In order to have better control over this, let's add "--compress" option to the "qemu-img rebase" command. Note that this option affects only the clusters which are actually being copied from the original backing file. The clusters which were uncompressed in the target image will remain so. Signed-off-by: Andrey Drobyshev <andrey.drobyshev@virtuozzo.com> Reviewed-by: Denis V. Lunev <den@openvz.org> Reviewed-by: Hanna Czenczek <hreitz@redhat.com> Message-ID: <20230919165804.439110-8-andrey.drobyshev@virtuozzo.com> Reviewed-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2023-09-20 00:58:03 +08: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")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
qemu-img: add compression option to rebase subcommand If we rebase an image whose backing file has compressed clusters, we might end up wasting disk space since the copied clusters are now uncompressed. In order to have better control over this, let's add "--compress" option to the "qemu-img rebase" command. Note that this option affects only the clusters which are actually being copied from the original backing file. The clusters which were uncompressed in the target image will remain so. Signed-off-by: Andrey Drobyshev <andrey.drobyshev@virtuozzo.com> Reviewed-by: Denis V. Lunev <den@openvz.org> Reviewed-by: Hanna Czenczek <hreitz@redhat.com> Message-ID: <20230919165804.439110-8-andrey.drobyshev@virtuozzo.com> Reviewed-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2023-09-20 00:58:03 +08: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
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
ERST
qemu-img: Add 'resize' command to grow/shrink disk images This patch adds a 'resize' command to grow/shrink disk images. This allows changing the size of disk images without copying to a new image file. Currently only raw files support resize. Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2010-04-24 16:12:12 +08:00
DEF("resize", img_resize,
qemu-img: Make documentation between .texi and .hx consistent These are also different and out of order for whatever reason. I'd like to automate this in the future, but for now let's put on the band-aid. In the case of resize, there were options missing from all three docstrings; the new string is based on the code. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Jeff Cody <jcody@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
2018-05-04 06:56:47 +08:00
"resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size")
qemu-img-cmds.hx: Add rST documentation fragments Add the rST versions of the documentation fragments. Once we've converted qemu-img.texi to rST we can delete the texi fragments; for the moment we leave them in place. (Commit created with the aid of emacs query-replace-regexp from "@var{\([^}]*\)}" to "\,(upcase \1))".) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200124162606.8787-5-peter.maydell@linaro.org
2020-01-25 00:26:02 +08:00
SRST
.. option:: resize [--object OBJECTDEF] [--image-opts] [-f FMT] [--preallocation=PREALLOC] [-q] [--shrink] FILENAME [+ | -]SIZE
ERST
Reference in New Issue Copy Permalink