Document better the PerlIO_{export,release,import}FILE()

relationships (or the lack thereof).

p4raw-id: //depot/perl@17485

diff --git a/perlio.c b/perlio.c
index b0d2f8c..11f600f 100644 (file)
--- a/perlio.c
+++ b/perlio.c
@@ -337,6 +337,7 @@ PerlIO_init(pTHX)
     sfset(sfstdout, SF_SHARE, 0);
 }
 
+/* This is not the reverse of PerlIO_exportFILE(), PerlIO_releaseFILE() is. */
 PerlIO *
 PerlIO_importFILE(FILE *stdio, const char *mode)
 {
@@ -3038,6 +3039,8 @@ PerlIO_funcs PerlIO_stdio = {
 #endif                          /* USE_STDIO_PTR */
 };
 
+/* Note that calls to PerlIO_exportFILE() are reversed using
+ * PerlIO_releaseFILE(), not importFILE. */
 FILE *
 PerlIO_exportFILE(PerlIO * f, const char *mode)
 {
@@ -3085,6 +3088,7 @@ PerlIO_findFILE(PerlIO *f)
     return PerlIO_exportFILE(f, Nullch);
 }
 
+/* Use this to reverse PerlIO_exportFILE calls. */
 void
 PerlIO_releaseFILE(PerlIO *p, FILE *f)
 {

diff --git a/pod/perlapio.pod b/pod/perlapio.pod
index 9da7f2d..1353ee0 100644 (file)
--- a/pod/perlapio.pod
+++ b/pod/perlapio.pod
@@ -321,6 +321,8 @@ C<PerlIO_close()> on the returned PerlIO *.
 The PerlIO is set to textmode. Use PerlIO_binmode if this is
 not the desired mode.
 
+This is B<not> the reverse of PerlIO_exportFILE().
+
 =item B<PerlIO_exportFILE(f,mode)>
 
 Given a PerlIO * create a 'native' FILE * suitable for passing to code
@@ -334,6 +336,7 @@ pushing a new :stdio "layer" onto the PerlIO *), which may affect future
 PerlIO operations on the original PerlIO *.
 You should not call C<fclose()> on the file unless you call
 C<PerlIO_releaseFILE()> to disassociate it from the PerlIO *.
+(And do not use PerlIO_importFILE() for doing to disassociation.)
 
 Calling this function repeatedly will create a FILE * on each call
 (and will push an :stdio layer each time as well).
@@ -344,6 +347,9 @@ Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
 complete. It is removed from the list of 'exported' FILE *s, and the
 associated PerlIO * should revert to its original behaviour.
 
+Use this to disassociate a file from a PerlIO * that was associated
+using PerlIO_exportFILE().
+
 =item B<PerlIO_findFILE(f)>
 
 Returns a native FILE * used by a stdio layer. If there is none, it