Portability and doc tweaks to PerlIO/XS stuff.

We are still "papering over the cracks" a bit,
but now it is good stiff card held on with epoxy.

p4raw-id: //depot/perlio@16496

1 files changed, 30 insertions, 9 deletions

diff --git a/pod/perlxstut.pod b/pod/perlxstut.pod
index a697ecb7d1..c7723af887 100644
--- a/pod/perlxstut.pod
+++ b/pod/perlxstut.pod
@@ -1229,20 +1229,40 @@ The real work is done in the standard typemap.
 B<But> you loose all the fine stuff done by the perlio layers. This
 calls the stdio function C<fputs()>, which knows nothing about them.
 
+For PerlIO *'s, there considered to be three kinds in the
+standard typemap C<InputStream> (T_IN), C<InOutStream> (T_INOUT) and
+C<OutputStream> (T_OUT), a bare C<PerlIO *> is considered a T_INOUT.
+If it matters in your code (see below for why it might) #define or typedef
+one of the specific names and use that as the type in your XS file.
+
+For streams coming I<from> perl the main difference is that
+C<OutputStream> will get the output PerlIO * - which may make
+a difference on a socket.
+
+For streams being handed I<to> perl a new file handle is created
+(i.e. a reference to a new glob) and associated with the PerlIO *
+provided. If the read/write state of the PerlIO * is not correct then you
+may get errors or warnings from when the file handle is used.
+So if you opened the PerlIO * as "w" it should really be an
+C<OutputStream> if open as "r" it should be an C<InputStream>.
+
 Now, suppose you want to use perlio layers in your XS. We'll use the
 perlio C<PerlIO_puts()> function as an example.
 
-For PerlIO *'s, we need a typemap because the standard typemap does
-not provide C<PerlIO *>:
+In the C part of the XS file (above the first MODULE line) you
+have
+
+	#define OutputStream	PerlIO *
+    or
+	typedef PerlIO *	OutputStream;
 
-	PerlIO *		T_INOUT
 
 And this is the XS code:
 
 	int
 	perlioputs(s, stream)
 		char *          s
-		PerlIO *	stream
+		OutputStream	stream
 	CODE:
 		RETVAL = PerlIO_puts(stream, s);
 	OUTPUT:
@@ -1270,6 +1290,10 @@ for a stdio C<FILE *>:
 	OUTPUT:
 		RETVAL
 
+(We also using bare PerlIO * as the type - so we get the I<input>
+PerlIO * of a socket - if this is undesirable use typedef or #define
+as above.)
+
 Note: C<PerlIO_findFILE()> will search the layers for a stdio
 layer. If it can't find one, it will call C<PerlIO_exportFILE()> to
 generate a new stdio C<FILE>. Please only call C<PerlIO_exportFILE()> if
@@ -1281,10 +1305,6 @@ generated by C<PerlIO_exportFILE()>.
 This applies to the perlio system only. For versions before 5.7,
 C<PerlIO_exportFILE()> is equivalent to C<PerlIO_findFILE()>.
 
-
-
-Getting fd's from filehandles
-
 =head2 Troubleshooting these Examples
 
 As mentioned at the top of this document, if you are having problems with
@@ -1335,7 +1355,8 @@ Jeff Okamoto <F<okamoto@corp.hp.com>>
 Reviewed and assisted by Dean Roehrich, Ilya Zakharevich, Andreas Koenig,
 and Tim Bunce.
 
-PerlIO material contributed by Lupe Christoph.
+PerlIO material contributed by Lupe Christoph, with some clarification
+by Nick Ing-Simmons.
 
 =head2 Last Changed