Bad $? assumptions.

p4raw-id: //depot/perl@13891

3 files changed, 68 insertions, 7 deletions

diff --git a/ext/POSIX/POSIX.pod b/ext/POSIX/POSIX.pod
index 7094f59087..4b727c53c1 100644
--- a/ext/POSIX/POSIX.pod
+++ b/ext/POSIX/POSIX.pod
@@ -191,7 +191,7 @@ to change file and directory owners and groups, see L<perlfunc/chown>.
 
 =item clearerr
 
-Use the method L<IO::Handle::clearerr()> instead, to reset the error
+Use the method C<IO::Handle::clearerr()> instead, to reset the error
 state (if any) and EOF state (if any) of the given stream.
 
 =item clock
@@ -1043,7 +1043,7 @@ argument means 'query'.)
 
 The following will set the LC_CTYPE behaviour according to the locale
 environment variables (the second argument C<"">).
-Please see your systems L<setlocale(3)> documentation for the locale
+Please see your systems C<setlocale(3)> documentation for the locale
 environment variables' meaning or consult L<perllocale>.
 
 	$loc = setlocale( LC_CTYPE, "" );
@@ -1983,9 +1983,56 @@ R_OK SEEK_CUR SEEK_END SEEK_SET STDIN_FILENO STDOUT_FILENO STDERR_FILENO W_OK X_
 
 WNOHANG WUNTRACED
 
+=over 16
+
+=item WNOHANG
+
+Do not suspend the calling process until a child process
+changes state but instead return immediately.
+
+=item WUNTRACED
+
+Catch stopped child processes.
+
+=back
+
 =item Macros
 
 WIFEXITED WEXITSTATUS WIFSIGNALED WTERMSIG WIFSTOPPED WSTOPSIG
 
+=over 16
+
+=item WIFEXITED
+
+WIFEXITED($?) returns true if the child process exited normally
+(C<exit()> or by falling off the end of C<main()>)
+
+=item WEXITSTATUS
+
+WEXITSTATUS($?) returns the normal exit status of the child process
+(only meaningful if WIFEXITED($?) is true)
+
+=item WIFSIGNALED
+
+WIFSIGNALED($?) returns true if the child process terminated because
+of a signal
+
+=item WTERMSIG
+
+WTERMSIG($?) returns the signal the child process terminated for
+(only meaningful if WIFSIGNALED($?) is true)
+
+=item WIFSTOPPED
+
+WIFSTOPPED($?) returns true if the child process is currently stopped
+(can happen only if you specified the WUNTRACED flag to waitpid())
+
+=item WSTOPSIG
+
+WSTOPSIG($?) returns the signal the child process was stopped for
+(only meaningful if WIFSTOPPED($?) is true)
+
+=back
+
 =back
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 193b0fb2fd..516d875fcf 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -5376,9 +5376,9 @@ supported on some platforms (see L<perlport>).  To be safe, you may need
 to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
 of C<IO::Handle> on any open handles.
 
-The return value is the exit status of the program as
-returned by the C<wait> call.  To get the actual exit value divide by
-256.  See also L</exec>.  This is I<not> what you want to use to capture
+The return value is the exit status of the program as returned by the
+C<wait> call.  To get the actual exit value shift left by eight (see below).
+See also L</exec>.  This is I<not> what you want to use to capture
 the output from a command, for that you should use merely backticks or
 C<qx//>, as described in L<perlop/"`STRING`">.  Return value of -1
 indicates a failure to start the program (inspect $! for the reason).
@@ -5386,8 +5386,9 @@ indicates a failure to start the program (inspect $! for the reason).
 Like C<exec>, C<system> allows you to lie to a program about its name if
 you use the C<system PROGRAM LIST> syntax.  Again, see L</exec>.
 
-Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>, killing the
-program they're running doesn't actually interrupt your program.
+Because C<system> and backticks block C<SIGINT> and C<SIGQUIT>,
+killing the program they're running doesn't actually interrupt
+your program.
 
     @args = ("command", "arg1", "arg2");
     system(@args) == 0
@@ -5400,6 +5401,9 @@ C<$?> like this:
     $signal_num  = $? & 127;
     $dumped_core = $? & 128;
 
+or more portably by using the W*() calls of the POSIX extension,
+see L<perlport> for more information.
+
 When the arguments get executed via the system shell, results
 and return codes will be subject to its quirks and capabilities.
 See L<perlop/"`STRING`"> and L</exec> for details.
diff --git a/pod/perlport.pod b/pod/perlport.pod
index 588b55d14b..a2133484dd 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -1779,6 +1779,16 @@ OS>, OS/390, VM/ESA)
 
 =item system LIST
 
+In general, do not assume the UNIX/POSIX semantics that you can shift
+the C<$?> left by eight to get the exit value, or that C<$? & 127>
+would give you the number of the signal that terminated the program,
+or that C<$? & 128> would test true if the program was terminated by a
+coredump.  Instead, use the POSIX W*() interfaces: for example, use
+WIFEXITED($?) an WEXITVALUE($?) to test for a normal exit and the exit
+value, and WIFSIGNALED($?) and WTERMSIG($?)  for a signal exit and the
+signal.  Core dumping is not a portable concept so there's no portable
+way to test for that.
+
 Only implemented if ToolServer is installed. (S<Mac OS>)
 
 As an optimization, may not call the command shell specified in