From nobody@FreeBSD.org  Wed Sep  9 14:14:16 2009
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 757A7106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  9 Sep 2009 14:14:16 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id 63B9A8FC12
	for <freebsd-gnats-submit@FreeBSD.org>; Wed,  9 Sep 2009 14:14:16 +0000 (UTC)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.3/8.14.3) with ESMTP id n89EEG6d087311
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 9 Sep 2009 14:14:16 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.3/8.14.3/Submit) id n89EEG6s087310;
	Wed, 9 Sep 2009 14:14:16 GMT
	(envelope-from nobody)
Message-Id: <200909091414.n89EEG6s087310@www.freebsd.org>
Date: Wed, 9 Sep 2009 14:14:16 GMT
From: Gennady Proskurin <gprspb.at.mail.dot.ru@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Subject: system(3) man page confuses users about "return value of 127"
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         138663
>Category:       docs
>Synopsis:       system(3) man page confuses users about "return value of 127"
>Confidential:   no
>Severity:       serious
>Priority:       low
>Responsible:    joel
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          sw-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Sep 09 14:20:00 UTC 2009
>Closed-Date:    
>Last-Modified:  Fri May 30 19:50:02 UTC 2014
>Originator:     Gennady Proskurin
>Release:        
>Organization:
>Environment:
FreeBSD gpr.nnz-home.ru 9.0-CURRENT FreeBSD 9.0-CURRENT #0 r197009M: Wed Sep  9 12:14:52 MSD 2009     gpr@gpr.nnz-home.ru:/usr/obj/usr/src/freebsd-head.svn/sys/GPR  amd64

>Description:
from system(3) man page

RETURN VALUES
     The system() function returns the exit status of the shell as returned by
     waitpid(2), or -1 if an error occurred when invoking fork(2) or
     waitpid(2).  A return value of 127 means the execution of the shell
     failed.


It should be clearly mentioned, that "return value of 127" applies to result of WEXITSTATUS() or something (termination status for a program), not to return value of system() itself.

>How-To-Repeat:
man 3 system
read section "RETURN VALUES"

>Fix:
man from OpenBSD, for example:

RETURN VALUES
     If a child process cannot be created, or the termination status of the
     shell cannot be obtained, system() returns -1 and sets errno to indicate
     the error.  If execution of the shell fails, system() returns the termi-
     nation status for a program that terminates with a call of exit(127).


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->gjb 
Responsible-Changed-By: gjb 
Responsible-Changed-When: Tue Sep 14 02:16:13 UTC 2010 
Responsible-Changed-Why:  
I'll take this. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 
Responsible-Changed-From-To: gjb->freebsd-doc 
Responsible-Changed-By: gjb 
Responsible-Changed-When: Fri Oct 1 11:50:49 UTC 2010 
Responsible-Changed-Why:  
Back to the pool for now due to lack of time. 


http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 
Responsible-Changed-From-To: freebsd-doc->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Mon Mar 5 00:22:38 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 
Responsible-Changed-From-To: eadler->freebsd-doc 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Wed Jul 25 06:49:27 UTC 2012 
Responsible-Changed-Why:  
I won't be getting to this any time soon 

http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 
Responsible-Changed-From-To: freebsd-doc->Take 
Responsible-Changed-By: joel 
Responsible-Changed-When: Mon Apr 22 11:05:48 UTC 2013 
Responsible-Changed-Why:  


http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 
Responsible-Changed-From-To: Take->joel 
Responsible-Changed-By: joel 
Responsible-Changed-When: Mon Apr 22 11:06:17 UTC 2013 
Responsible-Changed-Why:  
Take 

http://www.freebsd.org/cgi/query-pr.cgi?pr=138663 

From: Sevan Janiyan <venture37@geeklan.co.uk>
To: bug-followup@FreeBSD.org, gprspb.at.mail.dot.ru@FreeBSD.org
Cc:  
Subject: Re: docs/138663: system(3) man page confuses users about &quot;return
 value of 127&quot;
Date: Fri, 30 May 2014 20:42:15 +0100

 This is a multi-part message in MIME format.
 --------------050106090505020204050707
 Content-Type: text/plain; charset=ISO-8859-1; format=flowed
 Content-Transfer-Encoding: 7bit
 
 
 --------------050106090505020204050707
 Content-Type: text/plain; charset=UTF-8;
  name="system.txt"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment;
  filename="system.txt"
 
 Index: lib/libc/stdlib/system.3
 ===================================================================
 --- lib/libc/stdlib/system.3	(revision 266890)
 +++ lib/libc/stdlib/system.3	(working copy)
 @@ -80,8 +80,10 @@
  .Xr fork 2
  or
  .Xr waitpid 2 .
 -A return value of 127 means the execution of the shell
 -failed.
 +If execution of the shell fails,
 +.Fn system
 +returns the termination status for a program that terminates with a call of
 +.Xr exit 127 .
  .Sh SEE ALSO
  .Xr sh 1 ,
  .Xr execve 2 ,
 
 --------------050106090505020204050707--
>Unformatted:
