Fill in the PERLIO sections.
Nick Ing-Simmons [Sat, 20 Apr 2002 13:38:24 +0000 (13:38 +0000)]
p4raw-id: //depot/perlio@16018

pod/perlrun.pod

index 082a38e..564d111 100644 (file)
@@ -81,7 +81,7 @@ if you were so inclined, say
     eval 'exec perl -wS $0 ${1+"$@"}'
         if $running_under_some_shell;
 
-to let Perl see the B<-p> switch.  
+to let Perl see the B<-p> switch.
 
 A similar trick involves the B<env> program, if you have it.
 
@@ -302,7 +302,7 @@ sets debugging flags.  To watch how it executes your program, use
 B<-Dtls>.  (This works only if debugging is compiled into your
 Perl.)  Another nice value is B<-Dx>, which lists your compiled
 syntax tree.  And B<-Dr> displays compiled regular expressions;
-the format of the output is explained in L<perldebguts>. 
+the format of the output is explained in L<perldebguts>.
 
 As an alternative, specify a number instead of list of letters (e.g.,
 B<-D14> is equivalent to B<-Dtls>):
@@ -330,13 +330,13 @@ B<-D14> is equivalent to B<-Dtls>):
 
 All these flags require B<-DDEBUGGING> when you compile the Perl
 executable (but see L<Devel::Peek>, L<re> which may change this).
-See the F<INSTALL> file in the Perl source distribution 
+See the F<INSTALL> file in the Perl source distribution
 for how to do this.  This flag is automatically set if you include B<-g>
 option when C<Configure> asks you about optimizer/debugger flags.
 
 If you're just trying to get a print out of each line of Perl code
 as it executes, the way that C<sh -x> provides for shell scripts,
-you can't use Perl's B<-D> switch.  Instead do this 
+you can't use Perl's B<-D> switch.  Instead do this
 
   # If you have "env" utility
   env=PERLDB_OPTS="NonStop=1 AutoTrace=1 frame=2" perl -dS program
@@ -547,7 +547,7 @@ Here is an efficient way to delete all files older than a week:
 This is faster than using the B<-exec> switch of B<find> because you don't
 have to start a process on every filename found.  It does suffer from
 the bug of mishandling newlines in pathnames, which you can fix if
-you follow the example under B<-0>. 
+you follow the example under B<-0>.
 
 C<BEGIN> and C<END> blocks may be used to capture control before or after
 the implicit program loop, just as in B<awk>.
@@ -603,7 +603,7 @@ A C<-P> on a C<#!> line doesn't work.
 
 B<All> lines that begin with (whitespace and) a C<#> but
 do not look like cpp commands, are stripped, including anything
-inside Perl strings, regular expressions, and here-docs . 
+inside Perl strings, regular expressions, and here-docs .
 
 =item *
 
@@ -764,7 +764,7 @@ values of @INC.
 =item B<-V:>I<name>
 
 Prints to STDOUT the value of the named configuration variable.
-For example, 
+For example,
 
     $ perl -V:man.dir
 
@@ -855,45 +855,137 @@ enabled, and any subsequent options ignored.
 
 =item PERLIO
 
-A space-separated list of PerlIO layers.
+A space (or colon) separated list of PerlIO layers. If perl is built
+to use PerlIO system for IO (the default) these layers effect perl's IO.
+
+It is conventional to start layer names with a colon e.g. C<:perlio> to
+emphasise their similarity to variable "attributes". But the code that parses
+layer specification strings (which is also used to decode the PERLIO
+environment variable) treats the colon as a separator.
+
+The list becomes the default for I<all> perl's IO. Consequently only built-in
+layers can appear in this list, as external layers (such as :encoding()) need
+IO in  order to load them!. See L<"open pragma"|open> for how to add external
+encodings as defaults.
+
+The layers that it makes sense to include in the PERLIO environment
+variable are summarised below. For more details see L<PerlIO>.
 
 =over 8
 
 =item :bytes
 
-XXX
+Turns I<off> the C<:utf8> flag for the layer below.
+Unlikey to be useful in global PERLIO environment variable.
 
 =item :crlf
 
-XXX
+A layer that implements DOS/Windows like CRLF line endings.
+On read converts pairs of CR,LF to a single "\n" newline character.
+On write converts each "\n" to a CR,LF pair.
+Based on the C<:perlio> layer.
+
+=item :mmap
+
+A layer which implements "reading" of files by using C<mmap()> to
+make (whole) file appear in the process's address space, and then
+using that as PerlIO's "buffer". This I<may> be faster in certain
+circumstances for large files, and may result in less physical memory
+use when multiple processes are reading the same file.
 
-=item mmap
+Files which are not C<mmap()>-able revert to behaving like the C<:perlio>
+layer. Writes also behave like C<:perlio> layer as C<mmap()> for write
+needs extra house-keeping (to extend the file) which negates any advantage.
 
-XXX
+The C<:mmap> layer will not exist if platform does not support C<mmap()>.
 
-=item perlio
+=item :perlio
 
-XXX
+A from scratch implementation of buffering for PerlIO. Provides fast
+access to the buffer for C<sv_gets> which implements perl's readline/E<lt>E<gt>
+and in general attempts to minimize data copying.
 
-=item raw
+C<:perlio> will insert a C<:unix> layer below itself to do low level IO.
 
-XXX
+=item :raw
 
-=item stdio
+Arranges for all accesses go straight to the lowest level layer provided
+by the configration. That is it strips off any layers above that layer.
+(The intent - unless layers are then pushed on top again -
+is to make perl's C<read> behave like C<sysread>.)
 
-XXX
+Not really useful in PERLIO environment variable, instead just use C<:unix>
+layer explicitly.
 
-=item unix
+In perl5.6 and some books the C<:raw> layer (also called a discipline) is
+documented as the inverse of the C<:crlf> layer. That is not really the case.
+If you want UNIX line endings on a platform that normaly does CRLF translation
+the appropriate thing to do is to add C<:perlio> to PERLIO environment
+variable.
 
-XXX
+=item :stdio
+
+This layer provides PerlIO interface by wrapping system's ANSI C "stdio"
+library calls. The layer provides both buffering and IO.
+Note that C<:stdio> layer does I<not> do CRLF translation even if that
+is platforms normal behaviour. You will need a C<:crlf> layer above it
+to do that.
+
+=item :unix
+
+Lowest level layer which provides basic PerlIO operations in terms of
+UNIX/POSIX numeric file descriptor calls
+C<open(), read(), write(), lseek(), close()>
 
 =item :utf8
 
-XXX
+Turns on a flag on the layer below to tell perl that data sent to the
+stream should be converted to perl internal "utf8" form and that data from the
+stream should be considered as so encoded. On ASCII based platforms the
+encoding is UTF-8 and on EBCDIC platforms UTF-EBCDIC.
+May be useful in PERLIO environment variable to make UTF-8 the
+default. (To turn off that behaviour use C<:bytes> layer.)
+
+=item :win32
+
+On Win32 platfroms this I<experimental> layer uses native "handle" IO
+rather than unix-like numeric file descriptor layer. Known to be
+buggy in this release.
 
 =back
 
-For example, XXX ... for Unicode XXXX ... for Win32 XXX
+On all platforms the default set of layers should give acceptable results.
+
+For UNIX platfroms that will equivalent of "unix perlio" or "stdio".
+Configure is setup to prefer "stdio" implementation if system's library
+provides for fast access to the buffer, otherwise it uses the "unix perlio"
+implementation.
+
+On Win32 the default in this release is "unix crlf". Win32's "stdio"
+has a number of bugs/mis-features for perl IO which are somewhat
+C compiler verndor/version dependant. Using our own C<crlf> layer as
+the buffer avoids those issues and makes things more uniform.
+The C<crlf> layer provides CRLF to/from "\n" conversion as well as
+buffering.
+
+This release uses C<unix> as the bottom layer on Win32 and so still uses C
+compiler's numeric file descriptor routines. There is an experimental native
+C<win32> layer which is expected to be enhanced and should eventually replace
+the C<unix> layer.
+
+=item PERLIO_DEBUG
+
+If set to the name of a file or device then certain operations of PerlIO
+sub-system will be logged to that file (opened as append). Typical uses
+are UNIX:
+
+   PERLIO_DEBUG=/dev/tty perl script ...
+
+and Win32 approximate equivalent:
+
+   set PERLIO_DEBUG=CON
+   perl script ...
+
 
 =item PERLLIB
 
@@ -945,8 +1037,8 @@ PERL_ENCODING environment variable is consulted for an encoding name.
 
 A translation concealed rooted logical name that contains perl and the
 logical device for the @INC path on VMS only.  Other logical names that
-affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and 
-SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in 
+affect perl on VMS include PERLSHR, PERL_ENV_TABLES, and
+SYS$TIMEZONE_DIFFERENTIAL but are optional and discussed further in
 L<perlvms> and in F<README.vms> in the Perl source distribution.
 
 =item SYS$LOGIN (specific to the VMS port)