perlvar - expand and link to ${^OPEN} documentation

3 files changed, 26 insertions, 4 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 6ab61a4f10..9a5795c7e3 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -4539,8 +4539,9 @@ L<PerlIO> for more details).  For example:
 
 opens the UTF8-encoded file containing Unicode characters;
 see L<perluniintro>.  Note that if layers are specified in the
-three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
-usually set by the L<open> pragma or the switch C<-CioD>) are ignored.
+three-argument form, then default layers stored in
+L<C<${^OPEN}>|perlvar/${^OPEN}>
+(usually set by the L<open> pragma or the switch C<-CioD>) are ignored.
 Those layers will also be ignored if you specify a colon with no name
 following it.  In that case the default layer for the operating system
 (:raw on Unix, :crlf on Windows) is used.
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index cbb16ab993..89a7aa8a7b 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -313,7 +313,8 @@ The C<io> options mean that any subsequent open() (or similar I/O
 operations) in main program scope will have the C<:utf8> PerlIO layer
 implicitly applied to them, in other words, UTF-8 is expected from any
 input stream, and UTF-8 is produced to any output stream.  This is just
-the default, with explicit layers in open() and with binmode() one can
+the default set via L<C<${^OPEN}>|perlvar/${^OPEN}>,
+with explicit layers in open() and with binmode() one can
 manipulate streams as usual.  This has no effect on code run in modules.
 
 B<-C> on its own (not followed by any number or option list), or the
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 2b7a683a41..1d04f532f7 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -2255,10 +2255,30 @@ This variable was added in Perl v5.6.0.
 =item ${^OPEN}
 X<${^OPEN}>
 
-An internal variable used by PerlIO.  A string in two parts, separated
+An internal variable used by L<PerlIO>.  A string in two parts, separated
 by a C<\0> byte, the first part describes the input layers, the second
 part describes the output layers.
 
+This is the mechanism that applies the lexical effects of the L<open>
+pragma, and the main program scope effects of the C<io> or C<D> options
+for the L<-C command-line switch|perlrun/-C [I<numberE<sol>list>]> and
+L<PERL_UNICODE environment variable|perlrun/PERL_UNICODE>.
+
+The functions C<accept()>, C<open()>, C<pipe()>, C<readpipe()> (as well
+as the related C<qx> and C<`STRING`> operators), C<socket()>,
+C<socketpair()>, and C<sysopen()> are affected by the lexical value of
+this variable.  The implicit L</ARGV> handle opened by C<readline()> (or
+the related C<< <> >> and C<<< <<>> >>> operators) on passed filenames is
+also affected (but not if it opens C<STDIN>).  If this variable is not
+set, these functions will set the default layers as described in
+L<PerlIO/Defaults and how to override them>.
+
+C<open()> ignores this variable (and the default layers) when called with
+3 arguments and explicit layers are specified.  Indirect calls to these
+functions via modules like L<IO::Handle> are not affected as they occur
+in a different lexical scope.  Directory handles such as opened by
+C<opendir()> are not currently affected.
+
 This variable was added in Perl v5.8.0.
 
 =item $PERLDB