growfs: make exit codes more consistent

[freebsd_igalic.co]

Summary

We have overused err(1), so it's hard to distinguish when an error is
very, very serious, and when it's just a user-error, or even harmless.

This patch changes the current behaviour to distinguish between the following three:

1 for usage errors
2 for user-recoverable errors
3 for os-errors, most of which cannot be recovered.

[freebsd_igalic.co]

add context

[0mp]

I think this is a nice idea, but we should probably avoid using sysexits(3) for it (see https://reviews.freebsd.org/D27176). Also, it would be nice to update the manual page and explain the errors there (but it could be done in a separate commit probably).

[oshogbo]

What was motivation for this? Do you have any use case for that?

This is a delicate topic I think, there are some tools that return different exit codes I think the bsdgrep(1) is such example.
If you have a good motivation for this LGTM and I can commit this.

@jilles Whats your opinion about that?

[freebsd_igalic.co]

In D27161#609095, @oshogbo wrote:

What was motivation for this? Do you have any use case for that?

the motivation was a patch I was working on for cloud-init, https://github.com/canonical/cloud-init/pull/655 where i had to resort to exception based error handling, because so many,
vastly different error scenarios in growfs exit with 1

at least one of these could barely be called an error scenario at all (the case where growfs has nothing to do. especially when called with -N)

This is a delicate topic I think, there are some tools that return different exit codes I think the bsdgrep(1) is such example.
If you have a good motivation for this LGTM and I can commit this.

after @0mp's comment about https://reviews.freebsd.org/D27176 i would much rather wait for that to land and then revisit this

[jilles]

My suggestion is to change all the exit statuses that were changed to sysexits codes here to 2 instead.

"requested size %s is not larger than the current filesystem size %s" remains at 1 so that it can be checked for.

This results in a pattern much like grep(1) and test(1): the exit status is 0 if the file system has been or would be (with -N) enlarged, 1 if the file system is already at its maximum size and >1 if an error occurred. In practice, the ">1" is always 2, but this allows future expansion; scripts should check for the value 1, not for the value 2.

Please add this to the man page as well.

[freebsd_igalic.co]

In D27161#609617, @jilles wrote:

My suggestion is to change all the exit statuses that were changed to sysexits codes here to 2 instead.

"requested size %s is not larger than the current filesystem size %s" remains at 1 so that it can be checked for.

This results in a pattern much like grep(1) and test(1): the exit status is 0 if the file system has been or would be (with -N) enlarged, 1 if the file system is already at its maximum size and >1 if an error occurred. In practice, the ">1" is always 2, but this allows future expansion; scripts should check for the value 1, not for the value 2.

i can see one other class of error: recoverable error, caused by bogus input. the wrong size, unrecognised extension used on the size,
or heck even, wrong partition (or inability to find the correct device, or supplying a non-UFS.

all of these are recoverable, by correcting the input. however, they are not recoverable in scripts, as they are mostly human errors

OS errors, OTOH, are almost never recoverable without a major operation (running out of RAM or space, etc etc)

Please add this to the man page as well.

that's the plan. as soon as we have something solid.

I'd also like to continue this work in other tools that you find need it

[freebsd_igalic.co]

do *not* use sysexits, and document what we've done.

[0mp]

@oshogbo, do you still want to commit this patch? We may want to set Relnotes: yes to give a heads-up to the users.

[emaste]

sbin/growfs/growfs.8

92

Do you mean ≥ 1 (or > 0) instead of > 1?

[freebsd_igalic.co]

update patch which was left untouched since 2021

[pauamma_gundo.com]

Manual page nits fixable on commit if nothing else requires an updated diff.

sbin/growfs/growfs.8

94

95

MW and AHD both give this spelling first, although they also accept "signalled". So change here for consistency with the next line.

96

[freebsd_igalic.co]

address @PauAmma's review

[des]

sbin/growfs/growfs.8

93

[freebsd_igalic.co]

never start a sentence with .Nm

[emaste]

What are the "harmless errors"? If it's harmless it shouldn't be an error and shouldn't exit with nonzero.

[des]

sbin/growfs/growfs.8

93

As far as I can tell, there are no such cases in the code. If the filesystem is already the requested size we exit with 0. The only case where we exit with 1 is usage().

[freebsd_igalic.co]

there are no harmless errors (yet)

[freebsd_igalic.co]

s/signaled with/indicated by/g

also helps with spelling signaled vs signalled

[des]

I suggest changing the commit message to:

1 for usage errors
2 for recoverable errors
3 or higher for unrecoverable errors

[freebsd_igalic.co]

update commit message