This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlrun - Update PERLIO documentation
authorDan Book <grinnz@grinnz.com>
Thu, 12 Mar 2020 02:09:49 +0000 (22:09 -0400)
committerKarl Williamson <khw@cpan.org>
Fri, 13 Mar 2020 17:11:42 +0000 (11:11 -0600)
- Remove mention of several layers that have no business being set in PERLIO
- Clarify the role of :crlf and :stdio
- Update mentioned versions to indicate state of things in 5.30
- Consistently refer to layers with a leading colon

pod/perlrun.pod

index 7ceef8f..cbb16ab 100644 (file)
@@ -1069,27 +1069,12 @@ variable are briefly summarized below. For more details see L<PerlIO>.
 
 =over 8
 
-=item :bytes
-X<:bytes>
-
-A pseudolayer that turns the C<:utf8> flag I<off> for the layer below;
-unlikely to be useful on its own in the global PERLIO environment variable.
-You perhaps were thinking of C<:crlf:bytes> or C<:perlio:bytes>.
-
 =item :crlf
 X<:crlf>
 
 A layer which does CRLF to C<"\n"> translation distinguishing "text" and
-"binary" files in the manner of MS-DOS and similar operating systems.
-(It currently does I<not> mimic MS-DOS as far as treating of Control-Z
-as being an end-of-file marker.)
-
-=item :mmap
-X<:mmap>
-
-A layer that implements "reading" of files by using I<mmap>(2) to
-make an entire file appear in the process's address space, and then
-using that as PerlIO's "buffer".
+"binary" files in the manner of MS-DOS and similar operating systems,
+and also provides buffering similar to C<:perlio> on these architectures.
 
 =item :perlio
 X<:perlio>
@@ -1098,24 +1083,6 @@ This is a re-implementation of stdio-like buffering written as a
 PerlIO layer.  As such it will call whatever layer is below it for
 its operations, typically C<:unix>.
 
-=item :pop
-X<:pop>
-
-An experimental pseudolayer that removes the topmost layer.
-Use with the same care as is reserved for nitroglycerine.
-
-=item :raw
-X<:raw>
-
-A pseudolayer that manipulates other layers.  Applying the C<:raw>
-layer is equivalent to calling C<binmode($fh)>.  It makes the stream
-pass each byte as-is without translation.  In particular, both CRLF
-translation and intuiting C<:utf8> from the locale are disabled.
-
-Unlike in earlier versions of Perl, C<:raw> is I<not>
-just the inverse of C<:crlf>: other layers which would affect the
-binary nature of the stream are also removed or disabled.
-
 =item :stdio
 X<:stdio>
 
@@ -1130,42 +1097,31 @@ X<:unix>
 
 Low-level layer that calls C<read>, C<write>, C<lseek>, etc.
 
-=item :utf8
-X<:utf8>
-
-A pseudolayer that enables a flag in the layer below to tell Perl
-that output should be in utf8 and that input should be regarded as
-already in valid utf8 form. B<WARNING: It does not check for validity and as such
-should be handled with extreme caution for input, because security violations
-can occur with non-shortest UTF-8 encodings, etc.> Generally C<:encoding(UTF-8)> is
-the best option when reading UTF-8 encoded data.
-
 =item :win32
 X<:win32>
 
 On Win32 platforms this I<experimental> layer uses native "handle" IO
 rather than a Unix-like numeric file descriptor layer. Known to be
-buggy in this release (5.14).
+buggy in this release (5.30).
 
 =back
 
-The default set of layers should give acceptable results on all platforms
+The default set of layers should give acceptable results on all platforms.
 
-For Unix platforms that will be the equivalent of "unix perlio" or "stdio".
-Configure is set up to prefer the "stdio" implementation if the system's library
-provides for fast access to the buffer; otherwise, it uses the "unix perlio"
-implementation.
+For Unix platforms that will be the equivalent of ":unix:perlio" or ":stdio".
+Configure is set up to prefer the ":stdio" implementation if the system's library
+provides for fast access to the buffer (not common on modern architectures);
+otherwise, it uses the ":unix:perlio" implementation.
 
-On Win32 the default in this release (5.14) is "unix crlf". Win32's "stdio"
+On Win32 the default in this release (5.30) is ":unix:crlf". Win32's ":stdio"
 has a number of bugs/mis-features for Perl IO which are somewhat depending
-on the version and vendor of the C compiler. Using our own C<crlf> layer as
-the buffer avoids those issues and makes things more uniform.  The C<crlf>
-layer provides CRLF conversion as well as buffering.
+on the version and vendor of the C compiler. Using our own C<:crlf> layer as
+the buffer avoids those issues and makes things more uniform.
 
-This release (5.14) uses C<unix> as the bottom layer on Win32, and so still
+This release (5.30) uses C<:unix> as the bottom layer on Win32, and so still
 uses the C compiler's numeric file descriptor routines. There is an
-experimental native C<win32> layer, which is expected to be enhanced and
-should eventually become the default under Win32.
+experimental native C<:win32> layer, which is expected to be enhanced and
+may eventually become the default under Win32.
 
 The PERLIO environment variable is completely ignored when Perl
 is run in taint mode.