Bug 31415
| Summary: | install(1) is wrong about exit codes | ||
|---|---|---|---|
| Product: | Base System | Reporter: | Oliver Fromme <olli> |
| Component: | bin | Assignee: | freebsd-bugs (Nobody) <bugs> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | CC: | olli |
| Priority: | Normal | ||
| Version: | 4.4-RELEASE | ||
| Hardware: | Any | ||
| OS: | Any | ||
Oliver Fromme <olli@secnetix.de> wrote: > >Fix: > > I suggest a wording like this: > > DIAGNOSTICS > The install utility exits 0 on success, and a > value > 0 according to sysexits(3) otherwise. How about the following, which is a little more consistent with the rest of the man pages: DIAGNOSTICS The install utility exits 0 on success, and >0 if an error occurs. Achieved with: Index: install.1 =================================================================== RCS file: /ref/cvsf/src/usr.bin/xinstall/install.1,v retrieving revision 1.22 diff -u -r1.22 install.1 --- install.1 2001/08/21 15:59:55 1.22 +++ install.1 2001/10/21 21:48:15 @@ -176,9 +176,7 @@ .Pa /dev/null creates an empty file. .Sh DIAGNOSTICS -The -.Nm -utility exits 0 on success, and 1 otherwise. +.Ex -std .Sh FILES .Bl -tag -width INS@XXXX -compact .It Pa INS@XXXX Dima Dorfman wrote: > Oliver Fromme <olli@secnetix.de> wrote: > > >Fix: > > > > I suggest a wording like this: > > > > DIAGNOSTICS > > The install utility exits 0 on success, and a > > value > 0 according to sysexits(3) otherwise. > > How about the following, which is a little more consistent with the > rest of the man pages: > > DIAGNOSTICS > The install utility exits 0 on success, and >0 if an error occurs. Well ... Actually I think it would be a good thing to give people a hint to sysexits(3). It can help a lot to track down problems. In particular, people sometimes think that the exit values are errno numbers. In the case of the install utility, it exits with EX_OSERR (71) under certain conditions. This happened to someone on the -stable list, who thought it would be errno 71 (too many levels of remote in path), therefore searching for the problem at paths of his NFS mounts. Having said that, your suggested wording is at least better than the existing one (which is just plain wrong), so I can live with that. But it would certainly better to mention sysexits(3) somehow. If this affects other manpages, too, then all of those should be corrected. Regards Oliver -- Oliver Fromme, secnetix GmbH & Co KG, Oettingenstr. 2, 80538 München Any opinions expressed in this message may be personal to the author and may not necessarily reflect the opinions of secnetix in any way. "All that we see or seem is just a dream within a dream" (E. A. Poe) Oliver Fromme <oliver.fromme@secnetix.de> wrote: > > Dima Dorfman wrote: > > Oliver Fromme <olli@secnetix.de> wrote: > > > >Fix: > > > > > > I suggest a wording like this: > > > > > > DIAGNOSTICS > > > The install utility exits 0 on success, and a > > > value > 0 according to sysexits(3) otherwise. > > > > How about the following, which is a little more consistent with the > > rest of the man pages: > > > > DIAGNOSTICS > > The install utility exits 0 on success, and >0 if an error occurs. > > Well ... > > Actually I think it would be a good thing to give people > a hint to sysexits(3). It can help a lot to track down > problems. In particular, people sometimes think that the > exit values are errno numbers. > > In the case of the install utility, it exits with EX_OSERR > (71) under certain conditions. This happened to someone > on the -stable list, who thought it would be errno 71 (too > many levels of remote in path), therefore searching for the > problem at paths of his NFS mounts. > > Having said that, your suggested wording is at least better > than the existing one (which is just plain wrong), so I can > live with that. But it would certainly better to mention > sysexits(3) somehow. If this affects other manpages, too, > then all of those should be corrected. This problem is not particular to install(1). I think that instead of duplicating this information in all of the manual pages, it would be better to simply document it in a central place. intro(1) already talks a little about command return codes, so that might be a good place to mention it. Also note that not all programs actually use sysexits. Doing so is recommended in style(9) (although I think BDE doesn't really like that part (any more?)), but many commands don't and probably never will use them; these commands just exit with 1 on error. This is okay, since sysexits doesn't define 1 to mean anything. Perhaps something like this: Index: intro.1 =================================================================== RCS file: /home/dima/dfcvs/src/share/man/man1/intro.1,v retrieving revision 1.15 retrieving revision 1.15.1126.1 diff -u -r1.15 -r1.15.1126.1 --- intro.1 1999/08/28 00:19:40 1.15 +++ intro.1 2001/10/21 23:06:58 1.15.1126.1 @@ -32,7 +32,7 @@ .\" @(#)intro.1 8.2 (Berkeley) 12/30/93 .\" $FreeBSD$ .\" -.Dd December 30, 1993 +.Dd October 21, 2001 .Dt INTRO 1 .Os .Sh NAME @@ -55,14 +55,18 @@ .Pp All commands set a status value upon exit which may be tested to see if the command completed normally. -The exit values and their meanings are explained in the individual -manuals. Traditionally, the value 0 signifies successful -completion of the command. +Traditionally, the value 0 signifies successful +completion of the command, while a value >0 indicates an error. +Some commands attempt to describe the nature of the failure by using +errors codes as defined in +.Xr sysexits 3 , +while others simply set the status to an arbitrary value >0 (typically 1). .Sh SEE ALSO .Xr apropos 1 , .Xr man 1 , .Xr intro 2 , .Xr intro 3 , +.Xr sysexits 3 , .Xr intro 4 , .Xr intro 5 , .Xr intro 6 , Dima Dorfman wrote: > This problem is not particular to install(1). I think that instead of > duplicating this information in all of the manual pages, it would be > better to simply document it in a central place. intro(1) already > talks a little about command return codes, so that might be a good > place to mention it. That patch looks perfectly fine. Thanks! Go for it, please. Regards Oliver -- Oliver Fromme, secnetix GmbH & Co KG, Oettingenstr. 2, 80538 München Any opinions expressed in this message may be personal to the author and may not necessarily reflect the opinions of secnetix in any way. "All that we see or seem is just a dream within a dream" (E. A. Poe) State Changed From-To: open->closed Patches applied to -current as discussed, thanks for the report. |
The install(1) manpage says: DIAGNOSTICS The install utility exits 0 on success, and 1 otherwise. This is wrong; the install utility never exits 1. Instead, it uses sysexits codes, according to the sysexits(3) manpage. Fix: I suggest a wording like this: DIAGNOSTICS The install utility exits 0 on success, and a value > 0 according to sysexits(3) otherwise. How-To-Repeat: See the "diagnostics" section in the install(1) manpage. The compare the source code in src/usr.bin/xinstall/xinstall.c. Note the various places where err() and errx() is used. Also, you can simply try it: $ install -z install: illegal option -- z zsh: 88521 exit 64 install -z $ install / / install: /: Inappropriate file type or format zsh: 88522 exit 71 install / /