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

[Taylor R Campbell <campbell+netbsd-tech-userlevel%mumble.net@localhost>]

> 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'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.

> 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.

> 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.