missing information in man 3 system

[Peter Pentchev]

On Mon, Feb 11, 2013 at 12:04:38PM +0700, Erich Dollansky wrote:
> Hi,
> 
> man 3 system says:
> 
> 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.
[snip]
> 
> system () returns the result from 'error.c' in the result but shifted
> by 8 bits to the left.
> 
> I could not find this behaviour in the FreeBSD documentation.
> 
> So, is this the intended behaviour of system ()?
> 
> Should the documentation be uptdated?
> 
> Or did I simply miss something?

Yes, this is indeed the intended behavior of system(3) - it does say "as
returned by waitpid(2)" :)  Look at the manual page for the waitpid
system call (in section 2, as noted by the number in parentheses) - what
it returns is not the exact exit code of the finished program, it
encodes a bit more information there.  This return code ought to be
examined using the <sys/wait.h> macros described in the wait/waitpid
manual page; you need to do something like:

	if (WIFEXITED(code)) {
		printf("The program exited with code %d\n",
		    WEXITSTATUS(code));
	} else if (WIFSIGNALED(code)) {
		printf("The program was terminated by signal %d\n",
		    WTERMSIG(code));
	} else if (WIFSTOPPED(code)) {
		/**
		 * You will only get here if you explicitly ask to be
		 * notified about child processes being stopped using
		 * the flags of the waitpid() syscall; you will never
		 * get here when examining the exit code of system(3).
		 */
		printf("The program was stopped by signal %d\n",
		    WSTOPSIG(code));
	} else {
		printf("The program neither exited, nor was "
		    "terminated or stopped by a signal; what in "
		    "the world does wait() return value %d mean?!\n",
		    code);
	}

Yes, it may seem a bit convoluted at first glance, but it is indeed
necessary for the purpose of providing all the information in a single
return value.  Don't worry, this is something that everyone stumbles
into when making their first steps in system programming :) (pun
unintended ;)

Hope that helps!

G'luck,
Peter

-- 
Peter Pentchev	roam at ringlet.net roam at FreeBSD.org p.penchev at storpool.com
PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
Key fingerprint 2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
This sentence claims to be an Epimenides paradox, but it is lying.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20130211/27d009bf/attachment.sig>