Consolidated patch to 5.004_64

p4raw-id: //depot/perl@961

1 files changed, 30 insertions, 5 deletions

diff --git a/vms/perlvms.pod b/vms/perlvms.pod
index 4aa68008d5..89c4bbf623 100644
--- a/vms/perlvms.pod
+++ b/vms/perlvms.pod
@@ -663,12 +663,20 @@ list logical names.  For instance, if you say
 
 Perl will print C<ONCE UPON A TIME THERE WAS>.
 
-The %ENV keys C<home>, C<path>,C<term>, and C<user>
-return the CRTL "environment variables" of the same
-names, if these logical names are not defined.  The
-key C<default> returns the current default device
+The key C<default> returns the current default device
 and directory specification, regardless of whether
-there is a logical name DEFAULT defined..
+there is a logical name DEFAULT defined.  If you try to
+read an element of %ENV for which there is no corresponding
+logical name, and for which no corresponding CLI symbol
+exists (this is to identify "blocking" symbols only; to
+manipulate CLI symbols, see L<VMS::DCLSym>) then the key
+will be looked up in the CRTL-local environment array, and
+the corresponding value, if any returned.  This lets you
+get at C-specific keys like C<home>, C<path>,C<term>, and
+C<user>, as well as other keys which may have been passed
+directly into the C-specific array if Perl was called from
+another C program using the version of execve() or execle() 
+present in recent revisions of the DECCRTL.
 
 Setting an element of %ENV defines a supervisor-mode logical 
 name in the process logical name table.  C<Undef>ing or 
@@ -680,6 +688,23 @@ logical name translation after the deletion, so an inner-mode
 logical name or a name in another logical name table will 
 replace the logical name just deleted.  It is not possible
 at present to define a search list logical name via %ENV.
+It is also not possible to delete an element from the
+C-local environ array.
+
+Note that if you want to pass on any elements of the
+C-local environ array to a subprocess which isn't
+started by fork/exec, or isn't running a C program, you
+can "promote" them to logical names in the current
+process, which will then be inherited by all subprocesses,
+by saying
+
+    foreach my $key (qw[C-local keys you want promoted]) {
+       my $temp = $ENV{$key}; # read from C-local array
+       $ENV{$key} = $temp;    # and define as logical name
+    }
+
+(You can't just say C<$ENV{$key} = $ENV{$key}>, since the
+Perl optimizer is smart enough to elide the expression.)
 
 At present, the first time you iterate over %ENV using
 C<keys>, or C<values>,  you will incur a time penalty as all