better VMS docs for $?, exit(), and system()

Message-Id: <5.1.0.14.0.20010807155648.01ba3c98@exchi01>

p4raw-id: //depot/perl@11610

3 files changed, 38 insertions, 9 deletions

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 7a7fd49b55..1414b26afc 100644
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -1527,6 +1527,17 @@ Not implemented. (S<Mac OS>, Win32, Plan9)
 
 Not implemented. (Plan9, Win32)
 
+=item exit EXPR
+
+=item exit
+
+Emulates UNIX exit() (which considers C<exit 1> to indicate an error) by
+mapping the C<1> to SS$_ABORT (C<44>).  This behavior may be overridden
+with the pragma C<use vmsish 'exit'>.  As with the CRTL's exit()
+function, C<exit 0> is also mapped to an exit status of SS$_NORMAL
+(C<1>); this mapping cannot be overridden.  Any other argument to exit()
+is used directly as Perl's exit status. (VMS)
+
 =item getsockopt SOCKET,LEVEL,OPTNAME
 
 Not implemented. (S<Mac OS>, Plan9)
@@ -1737,6 +1748,11 @@ first token in its argument string.  Handles basic redirection
 Does not automatically flush output handles on some platforms.
 (SunOS, Solaris, HP-UX)
 
+The return value is POSIX-like (shifted up by 8 bits), which only allows
+room for a made-up value derived from the severity bits of the native
+32-bit condition code (unless overridden by C<use vmsish 'status'>). 
+For more details see L<perlvms/$?>. (VMS)
+
 =item times
 
 Only the first entry returned is nonzero. (S<Mac OS>)
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index d9b4c4173e..e66654d5bb 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -572,7 +572,7 @@ change the exit status of your program.  For example:
 
 Under VMS, the pragma C<use vmsish 'status'> makes C<$?> reflect the
 actual VMS exit status, instead of the default emulation of POSIX
-status.
+status; see L<perlvms/$?> for details.
 
 Also see L<Error Indicators>.
 
diff --git a/vms/perlvms.pod b/vms/perlvms.pod
index 4db64d4666..080c03d335 100644
--- a/vms/perlvms.pod
+++ b/vms/perlvms.pod
@@ -17,7 +17,7 @@ subdirectory of the Perl distribution.
 We hope these notes will save you from confusion and lost 
 sleep when writing Perl scripts on VMS.  If you find we've 
 missed something you think should appear here, please don't 
-hesitate to drop a line to vmsperl@newman.upenn.edu.
+hesitate to drop a line to vmsperl@perl.org.
 
 =head1 Installation
 
@@ -486,7 +486,7 @@ process, so there is no opportunity to perform operations in
 the subprocess before calling C<exec>.
 
 In general, the use of C<fork> and C<exec> to create 
-subprocess is not recommended under VMS; wherever possible, 
+subprocesses is not recommended under VMS; wherever possible, 
 use the C<system> operator or piped filehandles instead.
 
 =item getpwent
@@ -841,14 +841,26 @@ termination status of a process may or may not have been
 generated by an exception.  The next 8 bits are derived from
 the severity portion of the subprocess' exit status: if the
 severity was success or informational, these bits are all 0;
-otherwise, they contain the severity value shifted left one bit.
+if the severity was warning, they contain a value of 1; if the
+severity was error or fatal error, they contain the actual
+severity bits, which turns out to be a value of 2 for error
+and 4 for fatal error.  
+
 As a result, C<$?> will always be zero if the subprocess' exit
 status indicated successful completion, and non-zero if a
-warning or error occurred.  
+warning or error occurred.  Conversely, when setting C<$?> in
+an END block, an attempt is made to convert the POSIX value
+into a native status intelligible to the operating system upon
+exiting Perl.  What this boils down to is that setting C<$?>
+to zero results in the generic success value SS$_NORMAL, and
+setting C<$?> to a non-zero value results in the generic
+failure status SS$_ABORT.  See also L<perlport/exit>.
 
 The pragma C<use vmsish 'status'> makes C<$?> reflect the actual 
-VMS exit status, instead of the default emulation of POSIX status 
-described above.
+VMS exit status instead of the default emulation of POSIX status 
+described above.  This pragma also disables the conversion of
+non-zero values to SS$_ABORT when setting C<$?> in an END
+block (but zero will still be converted to SS$_NORMAL).
 
 =item $|
 
@@ -871,10 +883,11 @@ problems.
 
 =head1 Revision date
 
-This document was last updated on 26-Feb-2000, for Perl 5, 
-patchlevel 6.
+This document was last updated on 7-Aug-2001, for Perl 5, 
+patchlevel 8.
 
 =head1 AUTHOR
 
 Charles Bailey  <bailey@cor.newman.upenn.edu>
+Craig Berry  <craigberry@mac.com>
 Dan Sugalski  <dan@sidhe.org>