Change 11610 by jhi@alpha on 2001/08/08 00:12:00
Subject: [PATCH bleadperl] better VMS docs for $?, exit(), and system()
From: "Craig A. Berry" <[EMAIL PROTECTED]>
Date: Tue, 07 Aug 2001 20:01:53 -0500
Message-Id: <5.1.0.14.0.20010807155648.01ba3c98@exchi01>
Affected files ...
... //depot/perl/pod/perlport.pod#69 edit
... //depot/perl/pod/perlvar.pod#69 edit
... //depot/perl/vms/perlvms.pod#21 edit
Differences ...
==== //depot/perl/pod/perlport.pod#69 (text) ====
Index: perl/pod/perlport.pod
--- perl/pod/perlport.pod.~1~ Tue Aug 7 18:15:05 2001
+++ perl/pod/perlport.pod Tue Aug 7 18:15:05 2001
@@ -1527,6 +1527,17 @@
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 @@
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>)
==== //depot/perl/pod/perlvar.pod#69 (text) ====
Index: perl/pod/perlvar.pod
--- perl/pod/perlvar.pod.~1~ Tue Aug 7 18:15:05 2001
+++ perl/pod/perlvar.pod Tue Aug 7 18:15:05 2001
@@ -572,7 +572,7 @@
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>.
==== //depot/perl/vms/perlvms.pod#21 (text) ====
Index: perl/vms/perlvms.pod
--- perl/vms/perlvms.pod.~1~ Tue Aug 7 18:15:05 2001
+++ perl/vms/perlvms.pod Tue Aug 7 18:15:05 2001
@@ -17,7 +17,7 @@
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 [EMAIL PROTECTED]
+hesitate to drop a line to [EMAIL PROTECTED]
=head1 Installation
@@ -486,7 +486,7 @@
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 @@
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 @@
=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 <[EMAIL PROTECTED]>
+Craig Berry <[EMAIL PROTECTED]>
Dan Sugalski <[EMAIL PROTECTED]>
End of Patch.
