Confusing documentation about system(3) in 4.3BSD?

[Roy Smith]

	I was recently surprised to discover that if you run the following
program fragment:

	printf ("%d\n", system ("exit 0"));
	printf ("%d\n", system ("exit 1"));
	printf ("%d\n", system ("exit 2"));
	printf ("%d\n", system ("exit 3"));

you get:

	0
	256
	512
	768

	Clearly what is going on is that system() is returning the exit
status as described in wait(2), i.e. with the argument to exit() shifted up
one byte, and the low byte containing the termination status.  But, as I
read the man pages, the above fragment should have printed 0, 1, 2, and 3.

	System(3) says, "...returns the exit status of the shell."  Sh(1)
says, under "Special commands ... exit [n]", "the exit status is that of
the last command executed." and, under "Commands", "The value of a
simple-command is its exit status...", and under "Parameter substition",
describing the "?" parameter, "the value returned by the last executed
command in decimal."

	I would (and in fact, did) put all those together, and assume that
the following two code fragments (the first in a C program, the latter in a
shell script) would produce the same output.

	printf ("%d\n", system ("exit 1"));

	#!/bin/sh
	sh -c "exit 1"
	echo $?

but they don't; the first prints "256", the latter "1".

	Is this a case of my being thick (wouldn't be the first time) or is
the documentation indeed misleading?
-- 
Roy Smith, {allegra,cmcl2,philabs}!phri!roy
System Administrator, Public Health Research Institute
455 First Avenue, New York, NY 10016