More PerlIO documentation.

p4raw-id: //depot/perl@21293

diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm
index 5777679..9d1fa27 100644 (file)
--- a/lib/PerlIO.pm
+++ b/lib/PerlIO.pm
@@ -234,7 +234,8 @@ The following returns the B<names> of the PerlIO layers on a filehandle.
 
 The layers are returned in the order an open() or binmode() call would
 use them.  Note that the "default stack" depends on the operating
-system and on the perl version.
+system and on the Perl version, and both the compile-time and
+runtime configurations of Perl.
 
 The following table summarizes the default layers on UNIX-like and
 DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>:

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 9abc72e..8a41917 100644 (file)
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -24,6 +24,51 @@ The aim of the implementation is to provide the PerlIO API in a flexible
 and platform neutral manner. It is also a trial of an "Object Oriented
 C, with vtables" approach which may be applied to perl6.
 
+=head2 Basic Structure
+
+PerlIO is as a stack of layers.
+
+The low levels of the stack work with the low-level operating system
+calls (file descriptors in C) getting bytes in and out, the higher
+layers of the stack buffer, filter, and otherwise manipulate the I/O.
+Terms I<above> and I<below> are used to refer to the relative
+positioning of the stack layers.
+
+A layer contains a "vtable", the table of I/O operations (at C level
+a table of function pointers), and status flags.  The functions in the
+vtable implement operations like "open", "read", and "write".
+
+When I/O, for example "read", is requested, the request goes from Perl
+first down the stack using "read" functions of each layer, then at the
+bottom the input is requested from the operating system services, then
+the result is returned up the stack, finally being interpreted as Perl
+data.
+
+When you do an open() and specify extra PerlIO layers to be deployed,
+the layers you specify are "pushed" on top of the already existing
+default stack.  What exact layers are in this default stack depends on
+a lot of things: your operating system, Perl version, Perl compile
+time configuration, and Perl runtime configuration.  See L<PerlIO>,
+L<perlrun/PERLIO>, and L<open> for more information.
+
+binmode() operates similarly to open(): by default the specified
+layers are pushed on top of the existing stack.
+
+However, note that even as the specified layers are "pushed on top"
+for open() and binmode(), this doesn't mean that the effects are
+limited to the "top": PerlIO layers can be very 'active' and inspect
+and affect layers also deeper in the stack.  As an example there
+is a layer called "raw" which repeatedly "pops" layers until
+it reaches the first layer that has declared itself capable of
+handling binary data.  The "pushed" layers are processed in left-to-right
+order.
+
+sysopen() operates (unsurprisingly) at a lower level in the stack than
+open().  For example in UNIX or UNIX-like systems sysopen() operates
+directly at the level of file descriptors: in the terms of PerlIO
+layers, it uses only the "unix" layer, which is a rather thin wrapper
+on top of the UNIX file descriptors.
+
 =head2 Layers vs Disciplines
 
 Initial discussion of the ability to modify IO streams behaviour used