Bad $? assumptions.

p4raw-id: //depot/perl@13891

2 files changed, 19 insertions, 5 deletions

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