docs/138663: system(3) man page confuses users about "return value of 127"

[Gennady Proskurin]

>Number:         138663
>Category:       docs
>Synopsis:       system(3) man page confuses users about "return value of 127"
>Confidential:   no
>Severity:       serious
>Priority:       low
>Responsible:    freebsd-doc
>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:
>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 at 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:
>Unformatted: