X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=9abc72ec59ada77cd324b2f509366ece06d5b8e8;hb=c23d1eb0e18a49361001d26c686323d50b0c6d21;hp=94c0e98f8cb2391b274de48435621340877b262d;hpb=61bdadae648d36c1e21a073fae0f539b8ae699bf;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 94c0e98..9abc72e 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -420,7 +420,10 @@ struct.  It should also C<Unread()> any unconsumed data that has been
 read and buffered from the layer below back to that layer, so that it
 can be re-provided to what ever is now above.
 
-Returns 0 on success and failure.
+Returns 0 on success and failure.  If C<Popped()> returns I<true> then
+I<perlio.c> assumes that either the layer has popped itself, or the
+layer is super special and needs to be retained for other reasons.
+In most cases it should return I<false>.
 
 =item Open
 
@@ -478,6 +481,10 @@ and wait to be "pushed".  If a layer does provide C<Open()> it should
 normally call the C<Open()> method of next layer down (if any) and
 then push itself on top if that succeeds.
 
+If C<PerlIO_push> was performed and open has failed, it must
+C<PerlIO_pop> itself, since if it's not, the layer won't be removed
+and may cause bad problems.
+
 Returns C<NULL> on failure.
 
 =item Binmode
@@ -677,6 +684,23 @@ The application (or layer above) must ensure they are consistent.
 
 =head2 Implementing PerlIO Layers
 
+If you find the implementation document unclear or not sufficient,
+look at the existing perlio layer implementations, which include:
+
+=over
+
+=item * C implementations
+
+PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core.
+
+PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN.
+
+=item * Perl implementations
+
+PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN.
+
+=back
+
 If you are creating a PerlIO layer, you may want to be lazy, in other
 words, implement only the methods that interest you.  The other methods
 you can either replace with the "blank" methods