Re: style, sysexits(3), and man RETURN VALUES for sys programs
In article , wrote: >Le Sat, Jul 01, 2023 at 06:39:32PM -, Christos Zoulas a écrit : >> In article <20230603120221.0766b60...@jupiter.mumble.net>, >> Taylor R Campbell wrote: >> >> Date: Sat, 3 Jun 2023 13:45:44 +0200 >> >> From: tlaro...@polynum.com >> >> >> >> 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. >> >> I agree; nothing really uses sysexits except inside sendmail perhaps... >> It has been around for more than 40 years: >> >> ^As 00062/0/0 >> ^Ad D 1.1 81/10/15 20:29:54 eric 1 0 >> ^Ac date and time created 81/10/15 20:29:54 by eric >> >> and one would think that if it was useful, it would have caught on by now. >> > >Since you don't discuss anything particular to sysexits, your sentence >is then a broad, general judgement. So let's see: > >"NetBSD 1996 -- 2023 > >It has been around for 28 years. And one would think that if it was >useful, it would have caught on by now." It keeps changing and improving. Many pieces of the system are used elsewhere. >If the former is true, the latter is true. Is this latter true? > >As far as I'm concerned, even if the latter is true, in numbers, it has >absolutely >no bearing on the usefulness of NetBSD. Only on the stupidity of the >mob. Yes, it is numbers that make it less than useful. Shells don't even print exit values by default. >And since you mention init(8), the funny thing is that we are discussing >about a server that, generally, daemonizes and is hence reparented to >init(8)... Yes, but at this point init(8) can't do anything with those error codes. It would have been different if there was a launcher interface where the launcher could babysit a child and error numbers could provide a primitive communications channel. But there are better and more rich ways to communicate. > >And when it does not daemonize, it is in debugging mode, and providing >an information that the program has, and that will be lost when casting >all errors to EXIT_FAILURE, is a debugging feature... Most people don't expect to look at exit values for debugging, and then find the information in sysexits(3). >Not to mention that if there was the user interface equivalent of >strerror(3) (a sysstrerror(1)), one would not have to plague the programs >with variable strings, more or less accurate. Yes, and the place for programs to print that status would be shells. Unfortunately none of them do. >And, if a daemon was reparented to a daemon server, not closing stdin, >stdout and stderr, but redirecting then, this will allow to pass >commands to the server via its stdin, solving the problem that was >discussed, incidentally, in the course of the inetd(8) thread. And this >super daemon could make something of standardized return statuses if >only for stats purposes. > >sysexits(3) is a good idea. And this is probably why it hadn't caught >on. Well, everyone has a right to their own opinion. christos
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Le Sat, Jul 01, 2023 at 06:39:32PM -, Christos Zoulas a écrit : > In article <20230603120221.0766b60...@jupiter.mumble.net>, > Taylor R Campbell wrote: > >> Date: Sat, 3 Jun 2023 13:45:44 +0200 > >> From: tlaro...@polynum.com > >> > >> 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. > > I agree; nothing really uses sysexits except inside sendmail perhaps... > It has been around for more than 40 years: > > ^As 00062/0/0 > ^Ad D 1.1 81/10/15 20:29:54 eric 1 0 > ^Ac date and time created 81/10/15 20:29:54 by eric > > and one would think that if it was useful, it would have caught on by now. > Since you don't discuss anything particular to sysexits, your sentence is then a broad, general judgement. So let's see: "NetBSD 1996 -- 2023 It has been around for 28 years. And one would think that if it was useful, it would have caught on by now." If the former is true, the latter is true. Is this latter true? As far as I'm concerned, even if the latter is true, in numbers, it has absolutely no bearing on the usefulness of NetBSD. Only on the stupidity of the mob. And since you mention init(8), the funny thing is that we are discussing about a server that, generally, daemonizes and is hence reparented to init(8)... And when it does not daemonize, it is in debugging mode, and providing an information that the program has, and that will be lost when casting all errors to EXIT_FAILURE, is a debugging feature... Not to mention that if there was the user interface equivalent of strerror(3) (a sysstrerror(1)), one would not have to plague the programs with variable strings, more or less accurate. And, if a daemon was reparented to a daemon server, not closing stdin, stdout and stderr, but redirecting then, this will allow to pass commands to the server via its stdin, solving the problem that was discussed, incidentally, in the course of the inetd(8) thread. And this super daemon could make something of standardized return statuses if only for stats purposes. sysexits(3) is a good idea. And this is probably why it hadn't caught on. -- Thierry Laronde http://www.kergis.com/ http://kertex.kergis.com/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
Re: style, sysexits(3), and man RETURN VALUES for sys programs
In article <20230603120221.0766b60...@jupiter.mumble.net>, Taylor R Campbell wrote: >> Date: Sat, 3 Jun 2023 13:45:44 +0200 >> From: tlaro...@polynum.com >> >> 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. I agree; nothing really uses sysexits except inside sendmail perhaps... It has been around for more than 40 years: ^As 00062/0/0 ^Ad D 1.1 81/10/15 20:29:54 eric 1 0 ^Ac date and time created 81/10/15 20:29:54 by eric and one would think that if it was useful, it would have caught on by now. I think that it is best for most programs to use EXIT_SUCCESS/EXIT_FAILURE instead except for ones like init(8)... christos
Re: style, sysexits(3), and man RETURN VALUES for sys programs
>> Rhialto pointed me to sysexits(3) that was exactly what I was >> looking for (for inetd(8) revision). So kudos to him! > I deliberately didn't mention sysexits.h (or sysexits(3)) as I don't > think it is really appropriate here. I agree and I disagree. I agree that it certainly isn't the same sort of compelling use case that sendmail was back in the day. But, also, just beacuse you or I can't think of a use case for it immediately doesn't mean one won't appear. And, as far as I can see, it does no harm. The rc script might even be able to use it; that it doesn't now could mean nothing more than that there has historically been no such information for it to use, so why try? Certainly I can see a boot-time script caring about, for example, the difference between EX_CONFIG (fall back to a minimal configuration) versus EX_SOFTWARE (give up), possibly even retrying a few times in case of EX_TEMPFAIL. > Without that, all the calling program sees is "program exited with > status 78" so something went wrong, but what? Having to go back to > the manual (or system include file, which would be worse) to find out > what that error number means, is horrid - that's the way systems used > to work in the dark ages, when actually putting error messages, as > strings, in programs was too costly - and believe me, you don't want > to be in that environment. exit(EX_CONFIG) is no less informative than exit(1), for sure. Certainly, producing a message is good, but, if it's easy to do (which it appears to be, here), producing a message and exiting with a sysexits exit code is better. As a putative script writer, I'd far rather use a sysexits exit code than have to try to scrape stderr. > If there's also a message that explains the error, then you don't > need much in the way of specifics in the exit status, as all anyone > will look at is the error message [...] All any _human_ will, perhaps. Maybe _you_ are confdient nobody will ever want a script to take differential action based on the failure class; _I_ am not. > Unless there is a really good reason - which would amount to there > actually being something which will interpret the exit status from > inetd for more that ok/not ok then I wouldn't be going near sysexits. I would say that, if it's easy to produce a useful exit code, why not? It's no less informative than single-bit exit code; if a script just cares about success/failure, then sysexits exit codes work exactly as well as exit(1), and they do make a little more information available in case anyone wants to build a script that uses it. /~\ The ASCII Mouse \ / Ribbon Campaign X Against HTMLmo...@rodents-montreal.org / \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Le Sat, Jun 03, 2023 at 11:28:31PM +0700, Robert Elz a écrit : > Date:Sat, 3 Jun 2023 13:45:44 +0200 > From:tlaro...@polynum.com > Message-ID: > > | Rhialto pointed me to sysexits(3) that was exactly what I was looking > | for (for inetd(8) revision). So kudos to him! > > I deliberately didn't mention sysexits.h (or sysexits(3)) as I don't > think it is really appropriate here. > > sysexits works when the calling program (one which execs & then waits for > the one which is to use those exit values) understands the convention, and > can take action based upon the different exit codes. > But there is such a calling framework: it is called rc(8). That's the rc(8) that "ensures" (it can't if it is not called) that there is only one inetd(8) server; the program by itself has strictly no code to ensure that another server is not running... In the man page states: "should be run at boot time by /etc/rc" but it is not "should": it is "shall" because nothing else ensure uniqness. Since rc(8) is an automated framework, it has to understand exit values and certainly not to parse variable strings (why not confront rc(8) with i18n or l10n then?). Furthermore, you seem all to be OK with the fact that if a user asks: "Do integers wear white socks?", the program shall answer: "NO". I'm sorry, but the correct answer is: "NONSENSE" unless you want the user to ask: "Their socks are black then?" For rc(8), if every program handled by rc(8) was exiting with EX_USAGE, it would be a piece of cake to verify before release that rc(8) is at least up to date with the calling convention of the programs it handles. So, I use sysexits(3) in inetd(8) since if 0 for OK and whatever for anything else will do, sysexits(3) is a choice that is not less legitimate than anything else. And I do claim that sysexits was and still is a good idea ;-) -- Thierry Laronde http://www.kergis.com/ http://kertex.kergis.com/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Date:Sat, 3 Jun 2023 13:45:44 +0200 From:tlaro...@polynum.com Message-ID: | Rhialto pointed me to sysexits(3) that was exactly what I was looking | for (for inetd(8) revision). So kudos to him! I deliberately didn't mention sysexits.h (or sysexits(3)) as I don't think it is really appropriate here. sysexits works when the calling program (one which execs & then waits for the one which is to use those exit values) understands the convention, and can take action based upon the different exit codes. That is not the case for inetd - unless you're planning on creating another tool to run inetd (inetdd ?) which would start it and wait for exits from it, and decide what to do next based upon why inetd exited. sysexits was created with sendmail (or perhaps delivermail which preceded it) as a way to allow programs which send mail to know what happened when they transmit a message by an fork & exec of sendmail (these days most submission is done via SMTP, or the submission protocol variant of that, and those exit codes aren't really needed there any more). Without that, all the calling program sees is "program exited with status 78" so something went wrong, but what? Having to go back to the manual (or system include file, which would be worse) to find out what that error number means, is horrid - that's the way systems used to work in the dark ages, when actually putting error messages, as strings, in programs was too costly - and believe me, you don't want to be in that environment. If there's also a message that explains the error, then you don't need much in the way of specifics in the exit status, as all anyone will look at is the error message - and the most you want (possibly) to convey in the exit status is whether the reason for exiting is one that can be easily fixed, or one which will require real attention, and most programs don't even need that, just "all ok" or "failed" is all that is needed in the exit status. If there's no message (which includes syslog) then why isn't there? There are odd applications which really want to be silent, but I don't think inetd is one of those. Unless there is a really good reason - which would amount to there actually being something which will interpret the exit status from inetd for more that ok/not ok then I wouldn't be going near sysexits. kre
Re: style, sysexits(3), and man RETURN VALUES for sys programs
> Date: Sat, 3 Jun 2023 14:12:21 +0200 > From: tlaro...@polynum.com > > Le Sat, Jun 03, 2023 at 12:02:20PM +, Taylor R Campbell a écrit : > > > Date: Sat, 3 Jun 2023 13:45:44 +0200 > > > From: tlaro...@polynum.com > > > > > > 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. It's not really a loss of information: usually the error message printed to stderr is much more informative. The question is whether it's useful for composition, so that calling programs can make meaningful decisions to take useful action on the basis of the called program's exit code -- like the convention of zero for success, nonzero for failure, which is absolutely useful for composition. Unless you're devising a scheme to do that with sysexits(3), and implementing it systematically so that other programs derive some benefit from it, spending time to make inetd(8) scrupulously adhere to the sysexits(3) ontology of failure modes is likely a distraction from your main goals.
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Le Sat, Jun 03, 2023 at 12:25:01PM +, Taylor R Campbell a écrit : > > Date: Sat, 3 Jun 2023 14:12:21 +0200 > > From: tlaro...@polynum.com > > > > Le Sat, Jun 03, 2023 at 12:02:20PM +, Taylor R Campbell a écrit : > > > > Date: Sat, 3 Jun 2023 13:45:44 +0200 > > > > From: tlaro...@polynum.com > > > > > > > > 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. > > It's not really a loss of information: usually the error message > printed to stderr is much more informative. > > The question is whether it's useful for composition, so that calling > programs can make meaningful decisions to take useful action on the > basis of the called program's exit code -- like the convention of zero > for success, nonzero for failure, which is absolutely useful for > composition. > > Unless you're devising a scheme to do that with sysexits(3), and > implementing it systematically so that other programs derive some > benefit from it, spending time to make inetd(8) scrupulously adhere to > the sysexits(3) ontology of failure modes is likely a distraction from > your main goals. Don't worry: it is already fixed and was only a matter of minutes. I still plan to release the alpha on Monday the 5th (of June 2023...). -- Thierry Laronde http://www.kergis.com/ http://kertex.kergis.com/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Le Sat, Jun 03, 2023 at 12:02:20PM +, Taylor R Campbell a écrit : > > Date: Sat, 3 Jun 2023 13:45:44 +0200 > > From: tlaro...@polynum.com > > > > 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 http://www.kergis.com/ http://kertex.kergis.com/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
Re: style, sysexits(3), and man RETURN VALUES for sys programs
Le Sat, Jun 03, 2023 at 02:01:50PM +0200, Martin Husemann a écrit : > On Sat, Jun 03, 2023 at 01:45:44PM +0200, tlaro...@polynum.com wrote: > > Furthermore, I'm adding a RETURN VALUES section to inetd.8 and I think > > it should be standard practice for sys programs. > > That is for functions returning a value, the proper .Sh here would > be EXIT STATUS. > OK. -- Thierry Laronde http://www.kergis.com/ http://kertex.kergis.com/ Key fingerprint = 0FF7 E906 FBAF FE95 FD89 250D 52B1 AE95 6006 F40C
Re: style, sysexits(3), and man RETURN VALUES for sys programs
> Date: Sat, 3 Jun 2023 13:45:44 +0200 > From: tlaro...@polynum.com > > 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.
Re: style, sysexits(3), and man RETURN VALUES for sys programs
On Sat, Jun 03, 2023 at 01:45:44PM +0200, tlaro...@polynum.com wrote: > Furthermore, I'm adding a RETURN VALUES section to inetd.8 and I think > it should be standard practice for sys programs. That is for functions returning a value, the proper .Sh here would be EXIT STATUS. Martin
