From olli@lurza.secnetix.de  Sun Oct 21 14:19:56 2001
Return-Path: <olli@lurza.secnetix.de>
Received: from lurza.secnetix.de (lurza.secnetix.de [212.66.1.130])
	by hub.freebsd.org (Postfix) with ESMTP id 4DC9737B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 21 Oct 2001 14:19:55 -0700 (PDT)
Received: (from olli@localhost)
	by lurza.secnetix.de (8.11.6/8.11.6) id f9LLJsF88854;
	Sun, 21 Oct 2001 23:19:54 +0200 (CEST)
	(envelope-from oliver.fromme@secnetix.de)
Message-Id: <200110212119.f9LLJsF88854@lurza.secnetix.de>
Date: Sun, 21 Oct 2001 23:19:54 +0200 (CEST)
From: Oliver Fromme <olli@secnetix.de>
Reply-To: Oliver Fromme <olli@secnetix.de>
To: FreeBSD-gnats-submit@freebsd.org
Cc: Oliver Fromme <olli@secnetix.de>
Subject: install(1) is wrong about exit codes
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         31415
>Category:       bin
>Synopsis:       install(1) is wrong about exit codes
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-bugs
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Oct 21 14:20:00 PDT 2001
>Closed-Date:    Mon Oct 22 17:47:30 PDT 2001
>Last-Modified:  Mon Oct 22 17:47:46 PDT 2001
>Originator:     Oliver Fromme
>Release:        FreeBSD 4.4-RELEASE i386
>Organization:
secnetix GmbH & Co KG
>Environment:

   System: FreeBSD lurza.secnetix.de 4.4-RELEASE FreeBSD 4.4-RELEASE #0: Wed Oct 10 18:15:28 CEST 2001 olli@lurza.secnetix.de:/usr/obj/usr/src/sys/LURZA i386

>Description:

   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.

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

>Fix:

   I suggest a wording like this:

   DIAGNOSTICS
      The install utility exits 0 on success, and a
      value > 0 according to sysexits(3) otherwise.

>Release-Note:
>Audit-Trail:

From: Dima Dorfman <dima@trit.org>
To: Oliver Fromme <olli@secnetix.de>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: bin/31415: install(1) is wrong about exit codes 
Date: Sun, 21 Oct 2001 21:49:31 +0000

 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

From: Oliver Fromme <oliver.fromme@secnetix.de>
To: dima@trit.org (Dima Dorfman)
Cc: olli@secnetix.de (Oliver Fromme),
	freebsd-gnats-submit@freebsd.org
Subject: Re: bin/31415: install(1) is wrong about exit codes
Date: Mon, 22 Oct 2001 00:17:35 +0200 (CEST)

 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 Mnchen
 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)

From: Dima Dorfman <dima@trit.org>
To: Oliver Fromme <oliver.fromme@secnetix.de>
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 <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 ,
 

From: Oliver Fromme <oliver.fromme@secnetix.de>
To: dima@trit.org (Dima Dorfman)
Cc: oliver.fromme@secnetix.de (Oliver Fromme),
	freebsd-gnats-submit@freebsd.org
Subject: Re: bin/31415: install(1) is wrong about exit codes
Date: Mon, 22 Oct 2001 01:28:25 +0200 (CEST)

 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 Mnchen
 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 
State-Changed-By: dd 
State-Changed-When: Mon Oct 22 17:47:30 PDT 2001 
State-Changed-Why:  
Patches applied to -current as discussed, thanks for the report. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=31415 
>Unformatted:
