[Qemu-devel] [PATCH] qemu-img: Document check exit codes

[Qemu-devel] [PATCH] qemu-img: Document check exit codes

[Max Reitz]

The exit code 63 (check not supported by image format) was not even
documented in the comment above the check command in the source code;
add it, as it does indeed seem useful.

Also, document all of check's exit codes in the manpage.

Signed-off-by: Max Reitz <mreitz@redhat.com>
Reported-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-img.c    |  9 +++++----
 qemu-img.texi | 23 +++++++++++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/qemu-img.c b/qemu-img.c
index b3d2bc6..aa89ba2 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -580,10 +580,11 @@ static int collect_image_check(BlockDriverState *bs,
 /*
  * Checks an image for consistency. Exit codes:
  *
- * 0 - Check completed, image is good
- * 1 - Check not completed because of internal errors
- * 2 - Check completed, image is corrupted
- * 3 - Check completed, image has leaked clusters, but is good otherwise
+ *  0 - Check completed, image is good
+ *  1 - Check not completed because of internal errors
+ *  2 - Check completed, image is corrupted
+ *  3 - Check completed, image has leaked clusters, but is good otherwise
+ * 63 - Checks are not supported by the image format
  */
 static int img_check(int argc, char **argv)
 {
diff --git a/qemu-img.texi b/qemu-img.texi
index f84590e..7fa7a11 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -126,6 +126,29 @@ wrong fix or hiding corruption that has already occurred.
 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
 consistency checks.
 
+In case the image does not have any inconsistencies, check exits with @code{0}.
+Other exit codes indicate the kind of inconsistency found or if another error
+occured. The following table summarizes all exit codes of the check subcommand:
+
+@table @option
+
+@item 0
+Check completed, the image is (now) consistent
+@item 1
+Check not completed because of internal errors
+@item 2
+Check completed, image is corrupted
+@item 3
+Check completed, image has leaked clusters, but is not corrupted
+@item 63
+Checks are not supported by the image format
+
+@end table
+
+If @code{-r} is specified, exit codes representing the image state refer to the
+state after (the attempt on) repairing it. That is, a successful @code{-r all}
+will yield the exit code 0, independently of the image state before.
+
 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
 
 Create the new disk image @var{filename} of size @var{size} and format
-- 
1.9.3

Re: [Qemu-devel] [PATCH] qemu-img: Document check exit codes

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1242 bytes --]

On 06/02/2014 01:31 PM, Max Reitz wrote:
> The exit code 63 (check not supported by image format) was not even
> documented in the comment above the check command in the source code;
> add it, as it does indeed seem useful.
> 
> Also, document all of check's exit codes in the manpage.
> 
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> Reported-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-img.c    |  9 +++++----
>  qemu-img.texi | 23 +++++++++++++++++++++++
>  2 files changed, 28 insertions(+), 4 deletions(-)

>  
> +In case the image does not have any inconsistencies, check exits with @code{0}.
> +Other exit codes indicate the kind of inconsistency found or if another error
> +occured. The following table summarizes all exit codes of the check subcommand:

s/occured/occurred/

> +
> +If @code{-r} is specified, exit codes representing the image state refer to the
> +state after (the attempt on) repairing it. That is, a successful @code{-r all}

Not sure if this reads better, but:

s/attempt on/attempt at/

With the spelling fix,
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH] qemu-img: Document check exit codes

[Max Reitz]

On 02.06.2014 21:45, Eric Blake wrote:
> On 06/02/2014 01:31 PM, Max Reitz wrote:
>> The exit code 63 (check not supported by image format) was not even
>> documented in the comment above the check command in the source code;
>> add it, as it does indeed seem useful.
>>
>> Also, document all of check's exit codes in the manpage.
>>
>> Signed-off-by: Max Reitz <mreitz@redhat.com>
>> Reported-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>   qemu-img.c    |  9 +++++----
>>   qemu-img.texi | 23 +++++++++++++++++++++++
>>   2 files changed, 28 insertions(+), 4 deletions(-)
>>   
>> +In case the image does not have any inconsistencies, check exits with @code{0}.
>> +Other exit codes indicate the kind of inconsistency found or if another error
>> +occured. The following table summarizes all exit codes of the check subcommand:
> s/occured/occurred/

It's a bit embarrassing that the correct spelling was even part of the 
hunk environment. :-)

>> +
>> +If @code{-r} is specified, exit codes representing the image state refer to the
>> +state after (the attempt on) repairing it. That is, a successful @code{-r all}
> Not sure if this reads better, but:

Yes, the sentence is kind of hard to read, but I couldn't think of a 
nicer expression (I could drop the "representing the image state" part, 
but then people might ask how this applies to code 63 -- but then again, 
it just doesn't make any sense for that code, so...). That's why I added 
the explanatory example following it.

> s/attempt on/attempt at/
>
> With the spelling fix,
> Reviewed-by: Eric Blake <eblake@redhat.com>

Thank you,

Max