"Clean" implementation of binmode(FH)/":raw" identity.

New function table entry so all layer definitions need tweaking.
Extra function table entry allows a layer to remain on a binmode stack
New PerlIOBase_binmode allows easy implementation of default policy.

p4raw-id: //depot/perlio@17309

1 files changed, 27 insertions, 6 deletions

diff --git a/pod/perliol.pod b/pod/perliol.pod
index b4c8069723..81cbab17e7 100644
--- a/pod/perliol.pod
+++ b/pod/perliol.pod
@@ -98,6 +98,7 @@ same as the public C<PerlIO_xxxxx> functions:
   			int fd, int imode, int perm,
   			PerlIO *old,
   			int narg, SV **args);
+   IV		(*Binmode)(pTHX_ PerlIO *f);
    SV *		(*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
    IV		(*Fileno)(pTHX_ PerlIO *f);
    PerlIO *     (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
@@ -346,24 +347,31 @@ The size of the per-instance data structure, e.g.:
 
 	IV kind;
 
- XXX: explain all the available flags here
-
 =over 4
 
 =item * PERLIO_K_BUFFERED
 
+The layer is buffered.
+
+=item * PERLIO_K_RAW
+
+The layer is acceptable to have in a binmode(FH) stack - i.e. it does not
+(or will configure itself not to) transform bytes passing through it.
+
 =item * PERLIO_K_CANCRLF
 
+Layer can translate between "\n" and CRLF line ends.
+
 =item * PERLIO_K_FASTGETS
 
+Layer allows buffer snooping.
+
 =item * PERLIO_K_MULTIARG
 
 Used when the layer's open() accepts more arguments than usual. The
 extra arguments should come not before the C<MODE> argument. When this
 flag is used it's up to the layer to validate the args.
 
-=item * PERLIO_K_RAW
-
 =back
 
 =item Pushed
@@ -455,6 +463,16 @@ then push itself on top if that succeeds.
 
 Returns C<NULL> on failure.
 
+=item Binmode
+
+	IV        (*Binmode)(pTHX_ PerlIO *f);
+
+Optional. Used when C<:raw> layer is pushed (explicitly or as a result
+of binmode(FH)). If not present layer will be popped. If present
+should configure layer as binary (or pop itself) and return 0.
+If it returns -1 for error C<binmode> will fail with layer
+still on the stack.
+
 =item Getarg
 
 	SV *      (*Getarg)(pTHX_ PerlIO *f,
@@ -700,8 +718,11 @@ and so resumes reading from layer below.)
 =item "raw"
 
 A dummy layer which never exists on the layer stack. Instead when
-"pushed" it actually pops the stack(!), removing itself, and any other
-layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set.
+"pushed" it actually pops the stack removing itself, it then calls
+Binmode function table entry on all the layers in the stack - normally
+this (via PerlIOBase_binmode) removes any layers which do not have
+C<PERLIO_K_RAW> bit set. Layers can modify that behaviour by defining
+their own Binmode entry.
 
 =item "utf8"