documentation provides more details.
Perl is now in the process of evolving to follow the setting of
-the DECC$* feature logicals in the interpretation of UNIX pathnames.
+the DECC$* feature logical names in the interpretation of UNIX pathnames.
This is still a work in progress.
For handling extended characters, and case sensitivity, as long as
DECC$POSIX_COMPLIANT_PATHNAMES, DECC$FILENAME_UNIX_REPORT, and
DECC$FILENAME_UNIX_ONLY are not set, then the older Perl behavior
for conversions of file specifications from UNIX to VMS is followed,
-except that VMS paths with concealed rooted logicals are now
+except that VMS paths with concealed rooted logical names are now
translated correctly to UNIX paths.
With those features set, then new routines may handle the translation,
the state, and not the $^O setting.
For consistency, when the above feature is clear and when not
-otherwise overridden by DECC feature logicals, most Perl routines
+otherwise overridden by DECC feature logical names, most Perl routines
return file specifications using lower case letters only,
regardless of the case used in the arguments passed to them.
(This is true only when running under VMS; Perl respects the
except that the element separator is '|' instead of ':'. The
directory specifications may use either VMS or Unix syntax.
+=head1 PERL_VMS_EXCEPTION_DEBUG
+
+The PERL_VMS_EXCEPTION_DEBUG being defined as "ENABLE" will cause the VMS
+debugger to be invoked if a fatal exception that is not otherwise
+handled is raised. The purpose of this is to allow debugging of
+internal Perl problems that would cause such a condition.
+
+This allows the programmer to look at the execution stack and variables to
+find out the cause of the exception. As the debugger is being invoked as
+the Perl interpreter is about to do a fatal exit, continuing the execution
+in debug mode is usally not practical.
+
+Starting Perl in the VMS debugger may change the program execution
+profile in a way that such problems are not reproduced.
+
+The C<kill> function can be used to test this functionality from within
+a program.
+
+In typical VMS style, only the first letter of the value of this logical
+name is actually checked in a case insensitive mode, and it is considered
+enabled if it is the value "T","1" or "E".
+
+This logical name must be defined before Perl is started.
+
=head1 Command line
=head2 I/O redirection and backgrounding
DECC$FILENAME_UNIX_REPORT mode.
lchown, link, lstat, readlink, symlink
+
=over 4
=item File tests
specification without an explicit directory (e.g. C<DUA1:>), as
well as if passed a directory.
-There are DECC feature logicals AND ODS-5 volume attributes that
+There are DECC feature logical names AND ODS-5 volume attributes that
also control what values are returned for the date fields.
Note: Some sites have reported problems when using the file-access
return 1;
}
+
+=item die
+
+C<die> will force the native VMS exit status to be an SS$_ABORT code
+if neither of the $! or $? status values are ones that would cause
+the native status to be interpreted as being what VMS classifies as
+SEVERE_ERROR severity for DCL error handling.
+
+When the future POSIX_EXIT mode is active, C<die>, the native VMS exit
+status value will have either one of the C<$!> or C<$?> or C<$^E> or
+the UNIX value 255 encoded into it in a way that the effective original
+value can be decoded by other programs written in C, including Perl
+and the GNV package. As per the normal non-VMS behavior of C<die> if
+either C<$!> or C<$?> are non-zero, one of those values will be
+encoded into a native VMS status value. If both of the UNIX status
+values are 0, and the C<$^E> value is set one of ERROR or SEVERE_ERROR
+severity, then the C<$^E> value will be used as the exit code as is.
+If none of the above apply, the UNIX value of 255 will be encoded into
+a native VMS exit status value.
+
+Please note a significant difference in the behavior of C<die> in
+the future POSIX_EXIT mode is that it does not force a VMS
+SEVERE_ERROR status on exit. The UNIX exit values of 2 through
+255 will be encoded in VMS status values with severity levels of
+SUCCESS. The UNIX exit value of 1 will be encoded in a VMS status
+value with a severity level of ERROR. This is to be compatible with
+how the VMS C library encodes these values.
+
+The minimum severity level set by C<die> in a future POSIX_EXIT mode
+may be changed to be ERROR or higher before that mode becomes fully active
+depending on the results of testing and further review. If this is
+done, the behavior of c<DIE> in the future POSIX_EXIT will close enough
+to the default mode that most DCL shell scripts will probably not notice
+a difference.
+
+See C<$?> for a description of the encoding of the UNIX value to
+produce a native VMS status containing it.
+
+
=item dump
Rather than causing Perl to abort and dump core, the C<dump>
in midstream, the file may be left intact, but with a changed ACL
allowing you delete access.
+This behavior of C<unlink> is to be compatible with POSIX behavior
+and not traditional VMS behavior.
+
=item utime LIST
-Since ODS-2, the VMS file structure for disk files, does not keep
-track of access times, this operator changes only the modification
-time of the file (VMS revision date).
+This operator changes only the modification time of the file (VMS
+revision date) on ODS-2 volumes and ODS-5 volumes without access
+dates enabled. On ODS-5 volumes with access dates enabled, the
+true access time is modified.
=item waitpid PID,FLAGS
DELETE/LOGICAL *
You can imagine how bad things would be if, for example, the SYS$MANAGER
-or SYS$SYSTEM logicals were deleted.
+or SYS$SYSTEM logical names were deleted.
At present, the first time you iterate over %ENV using
C<keys>, or C<values>, you will incur a time penalty as all
won't be as slow, but they also won't reflect any changes
to logical name tables caused by other programs.
-You do need to be careful with the logicals representing process-permanent
-files, such as C<SYS$INPUT> and C<SYS$OUTPUT>. The translations for these
-logicals are prepended with a two-byte binary value (0x1B 0x00) that needs to be
-stripped off if you want to use it. (In previous versions of Perl it wasn't
-possible to get the values of these logicals, as the null byte acted as an
-end-of-string marker)
+You do need to be careful with the logical names representing
+process-permanent files, such as C<SYS$INPUT> and C<SYS$OUTPUT>.
+The translations for these logical names are prepended with a
+two-byte binary value (0x1B 0x00) that needs to be stripped off
+if you wantto use it. (In previous versions of Perl it wasn't
+possible to get the values of these logical names, as the null
+byte acted as an end-of-string marker)
=item $!
contain the actual value of 0 to 255 returned by that program
on a normal exit.
-With the _POSIX_EXIT macro set, the exit code of zero is represented
-as 1, and the values from 1 to 255 are encoded by the equation
-VMS_status = 0x35a000 + (exit_code * 8).
+With the _POSIX_EXIT macro set, the UNIX exit value of zero is
+represented as a VMS native status of 1, and the UNIX values
+from 2 to 255 are encoded by the equation:
+
+ VMS_status = 0x35a000 + (unix_value * 8) + 1.
+
+And in the special case of unix value 1 the encoding is:
+
+ VMS_status = 0x35a000 + 8 + 2 + 0x10000000.
For other termination statuses, the severity portion of the
-subprocess' exit status: if the severity was success or
+subprocess' exit status is used: if the severity was success or
informational, these bits are all 0; 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.
+which turns out to be a value of 2 for error and 4 for severe_error.
+Fatal is another term for the severe_error status.
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 or a program compliant with encoding
_POSIX_EXIT values was run and set a status.
-How can you tell the difference? You can not unless you look at
-the ${^CHILD_ERROR_NATIVE} code. The ${^CHILD_ERROR_NATIVE} code
-returns the actual VMS status value and check the severity bits.
-If the severity bits are clear, then the numeric value is code
-passed back from the application.
+How can you tell the difference between a non-zero status that is
+the result of a VMS native error status or an encoded UNIX status?
+You can not unless you look at the ${^CHILD_ERROR_NATIVE} value.
+The ${^CHILD_ERROR_NATIVE} value returns the actual VMS status value
+and check the severity bits. If the severity bits are equal to 1,
+then if the numeric value for C<$?> is between 2 and 255 or 0, then
+C<$?> accurately reflects a value passed back from a UNIX application.
+If C<$?> is 1, and the severity bits indicate a VMS error (2), then
+C<$?> is from a UNIX application exit value.
In practice, Perl scripts that call programs that return _POSIX_EXIT
-type status codes will be expecting those codes, and programs that
-call traditional VMS programs will be expecting the previous behavior.
+type status values will be expecting those values, and programs that
+call traditional VMS programs will either be expecting the previous
+behavior or just checking for a non-zero status.
+
+And success is always the value 0 in all behaviors.
-And success is always the code 0.
+When the actual VMS termination status of the child is an error,
+internally the C<$!> value will be set to the closest UNIX errno
+value to that error so that Perl scripts that test for error
+messages will see the expected UNIX style error message instead
+of a VMS message.
Conversely, when setting C<$?> in an END block, an attempt is made
to convert the POSIX value into a native status intelligible to
SS$_NORMAL, and setting C<$?> to a non-zero value results in the
generic failure status SS$_ABORT. See also L<perlport/exit>.
+With the future POSIX_EXIT mode set, setting C<$?> will cause the
+new value to also be encoded into C<$^E> so that the either the
+original parent or child exit status values of 0 to 255
+can be automatically recovered by C programs expecting _POSIX_EXIT
+behavior. If both a parent and a child exit value are non-zero, then it
+will be assumed that this is actually a VMS native status value to
+be passed through. The special value of 0xFFFF is almost a NOOP as
+it will cause the current native VMS status in the C library to
+become the current native Perl VMS status, and is handled this way
+as consequence of it known to not be a valid native VMS status value.
+It is recommend that only values in range of normal UNIX parent or
+child status numbers, 0 to 255 are used.
+
The pragma C<use vmsish 'status'> makes C<$?> reflect the actual
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).
+Do not use the pragma C<use vmsish 'status'> with the future
+POSIX_EXIT mode, as they are at times requesting conflicting
+actions and the consequence of ignoring this advice will be
+undefined to allow future improvements in the POSIX exit handling.
+
=item $|
Setting C<$|> for an I/O stream causes data to be flushed
projects / p5sagit/p5-mst-13.2.git / blobdiff