From nobody Mon Feb 9 05:19:13 2026 Delivered-To: importer@patchew.org Received-SPF: temperror (zoho.com: Error in retrieving data from DNS) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1554859764; cv=none; d=zoho.com; s=zohoarc; b=fV9QVa5fCBAiYvFOMHFavHd+DM3e76sPFbGBS2ZDWc+Ptw/6aMsE5Nv3NqQaUzAs0gAsZQykxznH5fgQ0uA08XbR7pk6JdDKO/6mQq8mO2PO0ObZnlkNy47Tc+7/Nqlj3dVXF/hX9fnO0c7RiiO4YRfpnuECYq6JscGF4fRdhCE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1554859764; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=6gzHb0LZpo+X1Niq3HMj5KKebl1qR1mGzHEd8fw1hTU=; b=GKayvXYLXQlgS0EJUQSJDpGTrLfkYmF6vk68utjSa7oFP979IM+DnzUyphvfGyWpOprwK/WdQSHXZw0lHZQKtkRQoUHepdP1Z9gFfnaB75NQdiaXpoOvNQ5Gtvaav+Q6Rcs0fmYZt3gN70CWjlJgmiJ/BGhhG5/w+aDC8fO05n0= ARC-Authentication-Results: i=1; mx.zoho.com; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1554859764646767.6818661776207; Tue, 9 Apr 2019 18:29:24 -0700 (PDT) Received: from localhost ([127.0.0.1]:51677 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE236-0001bF-C9 for importer@patchew.org; Tue, 09 Apr 2019 21:29:12 -0400 Received: from eggs.gnu.org ([209.51.188.92]:43374) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hE1yf-0007bG-LC for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hE1yd-0002gh-N8 for qemu-devel@nongnu.org; Tue, 09 Apr 2019 21:24:37 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37894) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hE1yP-0001sd-9E; Tue, 09 Apr 2019 21:24:21 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 9A10481235; Wed, 10 Apr 2019 01:24:20 +0000 (UTC) Received: from probe.bos.redhat.com (dhcp-17-206.bos.redhat.com [10.18.17.206]) by smtp.corp.redhat.com (Postfix) with ESMTP id A97061001E92; Wed, 10 Apr 2019 01:24:19 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org, qemu-block@nongnu.org Date: Tue, 9 Apr 2019 21:24:13 -0400 Message-Id: <20190410012413.31569-4-jsnow@redhat.com> In-Reply-To: <20190410012413.31569-1-jsnow@redhat.com> References: <20190410012413.31569-1-jsnow@redhat.com> X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Wed, 10 Apr 2019 01:24:20 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH RFC 3/3] qemu-img.texi: use macros for command summaries X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Eduardo Habkost , John Snow , armbru@redhat.com, Max Reitz , Cleber Rosa Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Use a macro to recall this text instead of re-entering it manually. Modify the pxtool script to create macros for each subcommand, then alter the qemu-img.texi file to recall these macros. Signed-off-by: John Snow --- qemu-img.texi | 28 ++++++++++++++-------------- scripts/pxtool.py | 4 ++++ 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/qemu-img.texi b/qemu-img.texi index 724f244ba1..c21a97e934 100644 --- a/qemu-img.texi +++ b/qemu-img.texi @@ -197,12 +197,12 @@ Command description: =20 @table @option =20 -@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{f= mt}] [-t @var{cache}] -o @var{options} @var{filename} +@qemuimgcmdamend =20 Amends the image format specific @var{options} for the image file @var{filename}. Not all file formats support this operation. =20 -@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-inte= rval=3D@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern= =3D@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var= {cache}] [-w] [-U] @var{filename} +@qemuimgcmdbench =20 Run a simple sequential I/O benchmark on the specified image. If @code{-w}= is specified, a write test is performed, otherwise a read test is performed. @@ -226,7 +226,7 @@ specified as well. For write tests, by default a buffer filled with zeros is written. This ca= n be overridden with a pattern byte specified by @var{pattern}. =20 -@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] = [--output=3D@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{f= ilename} +@qemuimgcmdcheck =20 Perform a consistency check on the disk image @var{filename}. The command = can output in the format @var{ofmt} which is either @code{human} or @code{json= }. @@ -262,7 +262,7 @@ If @code{-r} is specified, exit codes representing the = image state refer to the state after (the attempt at) repairing it. That is, a successful @code{-r = all} will yield the exit code 0, independently of the image state before. =20 -@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}]= [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename} +@qemuimgcmdcommit =20 Commit the changes recorded in @var{filename} in its base image or backing= file. If the backing file is smaller than the snapshot, then the backing file wi= ll be @@ -284,7 +284,7 @@ all images between @var{base} and the top image will be= invalid and may return garbage data when read. For this reason, @code{-b} implies @code{-d} (so t= hat the top image stays valid). =20 -@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F= @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{f= ilename2} +@qemuimgcmdcompare =20 Check if two images have the same content. You can compare images with different format or settings. @@ -325,7 +325,7 @@ Error on reading data =20 @end table =20 -@item convert [--object @var{objectdef}] [--image-opts] [--target-image-op= ts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{= src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}= ] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}= ] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename} +@qemuimgcmdconvert =20 Convert the disk image @var{filename} or a snapshot @var{snapshot_param} to disk image @var{output_filename} using format @var{output_fmt}. It can = be optionally compressed (@code{-c} @@ -366,7 +366,7 @@ creating compressed images. @var{num_coroutines} specifies how many coroutines work in parallel during the convert process (defaults to 8). =20 -@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backi= ng_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@v= ar{size}] +@qemuimgcmdcreate =20 Create the new disk image @var{filename} of size @var{size} and format @var{fmt}. Depending on the file format, you can add one or more @var{opti= ons} @@ -390,7 +390,7 @@ way. The size can also be specified using the @var{size} option with @code{-o}, it doesn't need to be specified separately in this case. =20 -@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=3D@v= ar{block_size}] [count=3D@var{blocks}] [skip=3D@var{blocks}] if=3D@var{inpu= t} of=3D@var{output} +@qemuimgcmddd =20 Dd copies from @var{input} file to @var{output} file converting it from @var{fmt} format to @var{output_fmt} format. @@ -401,7 +401,7 @@ dd will stop reading input after reading @var{blocks} i= nput blocks. =20 The size syntax is similar to dd(1)'s size syntax. =20 -@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--out= put=3D@var{ofmt}] [--backing-chain] [-U] @var{filename} +@qemuimgcmdinfo =20 Give information about the disk image @var{filename}. Use it in particular to know the size reserved on disk which can be different @@ -424,7 +424,7 @@ To enumerate information about each disk image in the a= bove chain, starting from qemu-img info --backing-chain snap2.qcow2 @end example =20 -@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--outp= ut=3D@var{ofmt}] [-U] @var{filename} +@qemuimgcmdmap =20 Dump the metadata of image @var{filename} and its backing file chain. In particular, this commands dumps the allocation state of every sector @@ -479,7 +479,7 @@ preallocated. For more information, consult @file{include/block/block.h} in QEMU's source code. =20 -@item measure [--output=3D@var{ofmt}] [-O @var{output_fmt}] [-o @var{optio= ns}] [--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{f= mt}] [-l @var{snapshot_param}] @var{filename}] +@qemuimgcmdmeasure =20 Calculate the file size required for a new image. This information can be= used to size logical volumes or SAN LUNs appropriately for the image that will = be @@ -509,11 +509,11 @@ been written to all sectors. This is the maximum siz= e that the image file can occupy with the exception of internal snapshots, dirty bitmaps, vmstate da= ta, and other advanced image format features. =20 -@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -= a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename} +@qemuimgcmdsnapshot =20 List, apply, create or delete snapshots in image @var{filename}. =20 -@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{= fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file}= [-F @var{backing_fmt}] @var{filename} +@qemuimgcmdrebase =20 Changes the backing file of an image. Only the formats @code{qcow2} and @code{qed} support changing the backing file. @@ -573,7 +573,7 @@ qemu-img rebase -b base.img diff.qcow2 At this point, @code{modified.img} can be discarded, since @code{base.img + diff.qcow2} contains the same information. =20 -@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--p= reallocation=3D@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{s= ize} +@qemuimgcmdresize =20 Change the disk image as if it had been created with @var{size}. =20 diff --git a/scripts/pxtool.py b/scripts/pxtool.py index 008fea839e..7ed5550b29 100755 --- a/scripts/pxtool.py +++ b/scripts/pxtool.py @@ -30,7 +30,11 @@ def generate_texi(conf): print("@table @option") for command, usage_strs in conf.items(): usage =3D " ".join(usage_strs) + macro =3D "qemuimgcmd{}".format(command) + print("@macro {}".format(macro)) print("@item {} {}".format(command, usage)) + print("@end macro") + print("@{}".format(macro)) print("@end table") =20 if __name__ =3D=3D '__main__': --=20 2.17.2