More perlio docs from Stas.

p4raw-id: //depot/perl@20286

1 files changed, 8 insertions, 6 deletions

diff --git a/pod/perliol.pod b/pod/perliol.pod
index 8b33e0253d..f8eb01ea8d 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -420,12 +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.
 
-When a PerlIO * is destructed all the layers should pop back to
-leave a NULL. However if ->Popped() returns true then perlio.c
-assumes that either the layer has popped itself, or the layer is
-super special and needs to be retained for other reasons.
-
-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
 
@@ -483,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