From owner-freebsd-bugs Sun Oct 21 16:10: 6 2001 Delivered-To: freebsd-bugs@hub.freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 2BF6637B401 for ; Sun, 21 Oct 2001 16:10:02 -0700 (PDT) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.4/8.11.4) id f9LNA2U17234; Sun, 21 Oct 2001 16:10:02 -0700 (PDT) (envelope-from gnats) Date: Sun, 21 Oct 2001 16:10:02 -0700 (PDT) Message-Id: <200110212310.f9LNA2U17234@freefall.freebsd.org> To: freebsd-bugs@FreeBSD.org Cc: From: Dima Dorfman Subject: Re: bin/31415: install(1) is wrong about exit codes Reply-To: Dima Dorfman Sender: owner-freebsd-bugs@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org The following reply was made to PR bin/31415; it has been noted by GNATS. From: Dima Dorfman To: Oliver Fromme Cc: olli@secnetix.de (Oliver Fromme), freebsd-gnats-submit@freebsd.org Subject: Re: bin/31415: install(1) is wrong about exit codes Date: Sun, 21 Oct 2001 23:09:04 +0000 Oliver Fromme wrote: > > Dima Dorfman wrote: > > Oliver Fromme 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 , To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-bugs" in the body of the message