Re: style, sysexits(3), and man RETURN VALUES for sys programs

[tlaronde%polynum.com@localhost]

Le Sat, Jun 03, 2023 at 12:02:20PM +0000, Taylor R Campbell a écrit :
> > Date: Sat, 3 Jun 2023 13:45:44 +0200
> > From: tlaronde%polynum.com@localhost
> > 
> > So I suggest to add a mention of sysexits(7) to style.
> 
> I don't think sysexits(7) is consistently used enough, or really
> useful enough, to warrant being a part of the style guide.  Very few
> programs, even those in src, use it, and I don't think anything
> _relies_ on it for semantics in calling programs.
> 

But I think it is a loss of information to put everything in
EXIT_FAILURE. All in all, the majority of scripts will simply test
against 0, so being more fine grained (there are only 15 exit values at
the moment) doesn't cause problems and, IMHO, adds some value that can
be useful.

> > But I'd like also to request some additions to sysexits(3):
> > [...]
> 
> Sounds like overthinking this, unless you see specific semantic value
> for composing programs that goes beyond the standard convention of 0
> for success and nonzero for failure.
> 
> There are extremely rare cases of making finer distinctions than that.
> For example, cmp(1) returns 0 for identical, 1 for difference, >1 for
> error.
> 

But in more complex cases, I think this can add value (I'm not
requesting to make it mandatory; but if sysexits(3) is not largely used,
it's perhaps simply but the majority---I was part of it---don't know it
exists...

> > Furthermore, I'm adding a RETURN VALUES section to inetd.8 and I think
> > it should be standard practice for sys programs.
> 
> Normally this would go under EXIT STATUS, not RETURN VALUES.

OK.

> 
> > BTW, and still concerning style, is there a defined way of generating a
> > MAN page needing to edit some part of the manual (ex.: usage) depending
> > on some macros defined or not (in the case of inetd.8---even if this is
> > not an actual problem because LIBWRAP is always defined---the [-l] flag
> > depends on the macro; but it is always present in the usage).
> 
> I'd just document it unconditionally, and if it's really important,
> mention in the text that it depends on a compile-time option.

OK (and, for inetd.8, LIBWRAP is on since 1996, so it was a hypothetical
question).
-- 
        Thierry Laronde <tlaronde +AT+ polynum +dot+ com>
                     http://www.kergis.com/
                    http://kertex.kergis.com/
Key fingerprint = 0FF7 E906 FBAF FE95 FD89  250D 52B1 AE95 6006 F40C