X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=26ad305fb037f0a9a9777d19f9f7df61a5b798ab;hb=36dfb0728c176423708a8d381586c8e380e47696;hp=eb6433a97a232f52d3b70cbe7ab54d02f309c7d3;hpb=eae154c7dcbb63935731f10277d6aa4e40e86a6c;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perliol.pod b/pod/perliol.pod
index eb6433a..26ad305 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -26,13 +26,13 @@ C, with vtables" approach which may be applied to perl6.
 
 =head2 Basic Structure
 
-PerlIO is as a stack of layers.
+PerlIO is 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.
+layers of the stack buffer, filter, and otherwise manipulate the I/O,
+and return characters (or bytes) to Perl.  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
@@ -44,11 +44,17 @@ bottom the input is requested from the operating system services, then
 the result is returned up the stack, finally being interpreted as Perl
 data.
 
+The requests do not necessarily go always all the way down to the
+operating system: that's where PerlIO buffering comes into play.
+
 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>,
+default stack.  One way to see it is that "operating system is
+on the left" and "Perl is on the right".
+
+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
@@ -553,6 +559,10 @@ pushed. e.g. ":encoding(ascii)" would return an SvPV with value
 "ascii". (I<param> and I<flags> arguments can be ignored in most
 cases)
 
+C<Dup> uses C<Getarg> to retrieve the argument originally passed to
+C<Pushed>, so you must implement this function if your layer has an
+extra argument to C<Pushed> and will ever be C<Dup>ed.
+
 =item Fileno
 
 	IV        (*Fileno)(pTHX_ PerlIO *f);
@@ -727,10 +737,46 @@ The application (or layer above) must ensure they are consistent.
 
 =back
 
+=head2 Utilities
+
+To ask for the next layer down use PerlIONext(PerlIO *f).
+
+To check that a PerlIO* is valid use PerlIOValid(PerlIO *f).  (All
+this does is really just to check that the pointer is non-NULL and
+that the pointer behind that is non-NULL.)
+
+PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words,
+the C<PerlIOl*> pointer.
+
+PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type.
+
+Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either
+calls the I<callback> from the functions of the layer I<f> (just by
+the name of the IO function, like "Read") with the I<args>, or if
+there is no such callback, calls the I<base> version of the callback
+with the same args, or if the f is invalid, set errno to EBADF and
+return I<failure>.
+
+Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls
+the I<callback> of the functions of the layer I<f> with the I<args>,
+or if there is no such callback, set errno to EINVAL.  Or if the f is
+invalid, set errno to EBADF and return I<failure>.
+
+Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls
+the I<callback> of the functions of the layer I<f> with the I<args>,
+or if there is no such callback, calls the I<base> version of the
+callback with the same args, or if the f is invalid, set errno to
+EBADF.
+
+Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the
+I<callback> of the functions of the layer I<f> with the I<args>, or if
+there is no such callback, set errno to EINVAL.  Or if the f is
+invalid, set errno to EBADF.
+
 =head2 Implementing PerlIO Layers
 
 If you find the implementation document unclear or not sufficient,
-look at the existing perlio layer implementations, which include:
+look at the existing PerlIO layer implementations, which include:
 
 =over