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

diff --git a/pod/perliol.pod b/pod/perliol.pod
index a2eeed3..26ad305 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -559,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);
@@ -733,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