X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapio.pod;h=1c57f9a9a89b1f4354162550aac0c21a393bc97b;hb=3c20a832e0afaa3d5dac4e9889c4ce2f06a128c5;hp=ad80a6c2e57d97b62cfae35ff5c6556fe4030cb3;hpb=06936a3ca90ea0922bedd964642e85df92d1986a;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlapio.pod b/pod/perlapio.pod
index ad80a6c..1c57f9a 100644
--- a/pod/perlapio.pod
+++ b/pod/perlapio.pod
@@ -56,7 +56,7 @@ perlapio - perl's IO abstraction interface.
     char   *PerlIO_get_base(PerlIO *f);
     int     PerlIO_get_bufsiz(PerlIO *f);
 
-    PerlIO *PerlIO_importFILE(FILE *stdio, int flags);
+    PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
     FILE   *PerlIO_exportFILE(PerlIO *f, int flags);
     FILE   *PerlIO_findFILE(PerlIO *f);
     void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);
@@ -104,7 +104,7 @@ above abstraction which allows perl more control over how IO is done
 as it decouples IO from the way the operating system and C library
 choose to do things. For USE_PERLIO PerlIO * has an extra layer of
 indirection - it is a pointer-to-a-pointer.  This allows the PerlIO *
-to remain with a known value while swapping the implementation arround
+to remain with a known value while swapping the implementation around
 underneath I<at run time>. In this case all the above are true (but
 very simple) functions which call the underlying implementation.
 
@@ -138,7 +138,7 @@ These correspond to fopen()/fdopen() and the arguments are the same.
 Return C<NULL> and set C<errno> if there is an error.  There may be an
 implementation limit on the number of open handles, which may be lower
 than the limit on the number of open files - C<errno> may not be set
-when C<NULL> is returned if this limnit is exceeded.
+when C<NULL> is returned if this limit is exceeded.
 
 =item B<PerlIO_reopen(path,mode,f)>
 
@@ -160,12 +160,17 @@ so it is (currently) legal to use C<printf(fmt,...)> in perl sources.
 
 =item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)>
 
-These correspond to fread() and fwrite(). Note that arguments are
-different, there is only one "count" and order has "file"
-first. Returns a byte count if successful (which may be zero), returns
-negative value and sets C<errno> on error.  Depending on
-implementation C<errno> may be C<EINTR> if operation was interrupted
-by a signal.
+These correspond functionally to fread() and fwrite() but the
+arguments and return values are different.  The PerlIO_read() and
+PerlIO_write() signatures have been modeled on the more sane low level
+read() and write() functions instead: The "file" argument is passed
+first, there is only one "count", and the return value can distinguish
+between error and C<EOF>.
+
+Returns a byte count if successful (which may be zero or
+positive), returns negative value and sets C<errno> on error.
+Depending on implementation C<errno> may be C<EINTR> if operation was
+interrupted by a signal.
 
 =item B<PerlIO_close(f)>
 
@@ -220,15 +225,19 @@ This corresponds to clearerr(), i.e., clears 'error' and (usually)
 
 This corresponds to fflush().  Sends any buffered write data to the
 underlying file.  If called with C<NULL> this may flush all open
-streams (or core dump).  Calling on a handle open for read only, or on
-which last operation was a read of some kind may lead to undefined
-behaviour.
+streams (or core dump with some USE_STDIO implementations).  Calling
+on a handle open for read only, or on which last operation was a read
+of some kind may lead to undefined behaviour on some USE_STDIO
+implementations.  The USE_PERLIO (layers) implementation tries to
+behave better: it flushes all open streams when passed C<NULL>, and
+attempts to retain data on read streams either in the buffer or by
+seeking the handle to the current logical position.
 
 =item B<PerlIO_seek(f,offset,whence)>
 
 This corresponds to fseek().  Sends buffered write data to the
 underlying file, or discards any buffered read data, then positions
-the file desciptor as specified by B<offset> and B<whence> (sic).
+the file descriptor as specified by B<offset> and B<whence> (sic).
 This is the correct thing to do when switching between read and write
 on the same handle (see issues with PerlIO_flush() above).  Offset is
 of type C<Off_t> which is a perl Configure value which may not be same
@@ -289,7 +298,7 @@ problem. However in other cases then mechanisms must exist to create a
 FILE * which can be passed to library code which is going to use stdio
 calls.
 
-The fisrt step is to add this line:
+The first step is to add this line:
 
    #define PERLIO_NOT_STDIO 0
 
@@ -303,33 +312,58 @@ changes in this area.
 
 =over 4
 
-=item B<PerlIO_importFILE(f,flags)>
+=item B<PerlIO_importFILE(f,mode)>
 
-Used to get a PerlIO * from a FILE *.  May need additional arguments,
-interface under review.
+Used to get a PerlIO * from a FILE *.
 
-The flags argument was meant to be used for read vs write vs
-read/write information. In hindsight it would have been better to make
-it a char *mode as in fopen/freopen.
+The mode argument should be a string as would be passed to
+fopen/PerlIO_open.  If it is NULL then - for legacy support - the code
+will (depending upon the platform and the implementation) either
+attempt to empirically determine the mode in which I<f> is open, or
+use "r+" to indicate a read/write stream.
 
-=item B<PerlIO_exportFILE(f,flags)>
+Once called the FILE * should I<ONLY> be closed by calling
+C<PerlIO_close()> on the returned PerlIO *.
 
-Given a PerlIO * return a 'native' FILE * suitable for passing to code
-expecting to be compiled and linked with ANSI C I<stdio.h>.
+The PerlIO is set to textmode. Use PerlIO_binmode if this is
+not the desired mode.
 
-The fact that such a FILE * has been 'exported' is recorded, and may
-affect future PerlIO operations on the original PerlIO *.
+This is B<not> the reverse of PerlIO_exportFILE().
 
-=item B<PerlIO_findFILE(f)>
+=item B<PerlIO_exportFILE(f,mode)>
+
+Given a PerlIO * create a 'native' FILE * suitable for passing to code
+expecting to be compiled and linked with ANSI C I<stdio.h>.  The mode
+argument should be a string as would be passed to fopen/PerlIO_open.
+If it is NULL then - for legacy support - the FILE * is opened in same
+mode as the PerlIO *.
+
+The fact that such a FILE * has been 'exported' is recorded, (normally
+by 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 *.  (Do not use PerlIO_importFILE()
+for doing the disassociation.)
 
-Returns previously 'exported' FILE * (if any).  Placeholder until
-interface is fully defined.
+Calling this function repeatedly will create a FILE * on each call
+(and will push an :stdio layer each time as well).
 
 =item B<PerlIO_releaseFILE(p,f)>
 
 Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is
-complete. It is removed from list of 'exported' FILE *s, and
-associated PerlIO * should revert to original behaviour.
+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
+will create one with PerlIO_exportFILE. In either case the FILE *
+should be considered as belonging to PerlIO subsystem and should
+only be closed by calling C<PerlIO_close()>.
+
 
 =back
 
@@ -351,8 +385,8 @@ traditional way if a handle does not support them.
 =item B<PerlIO_fast_gets(f)>
 
 Returns true if implementation has all the interfaces required to
-allow perl's C<sv_gets> to "bypass" normal IO mechanism.
-This can vary from handle to handle.
+allow perl's C<sv_gets> to "bypass" normal IO mechanism.  This can
+vary from handle to handle.
 
   PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                         PerlIO_canset_cnt(f) && \
@@ -426,13 +460,13 @@ happened to C<read()> (or whatever) last time IO was requested.
 
 The new interface to the USE_PERLIO implementation. The layers ":crlf"
 and ":raw" are only ones allowed for other implementations and those
-are silently ignored. Use PerlIO_binmode() below for the portable
-case.
+are silently ignored. (As of perl5.8 ":raw" is deprecated.)  Use
+PerlIO_binmode() below for the portable case.
 
 =item PerlIO_binmode(f,ptype,imode,layers)
 
 The hook used by perl's C<binmode> operator.
-B<ptype> is perl's charcter for the kind of IO:
+B<ptype> is perl's character for the kind of IO:
 
 =over 8
 
@@ -446,12 +480,13 @@ B<ptype> is perl's charcter for the kind of IO:
 
 B<imode> is C<O_BINARY> or C<O_TEXT>.
 
-B<layers> is a string of layers to apply, only ":raw" or :"crlf" make
-sense in the non USE_PERLIO case.
+B<layers> is a string of layers to apply, only ":crlf" makes sense in
+the non USE_PERLIO case. (As of perl5.8 ":raw" is deprecated in favour
+of passing NULL.)
 
 Portable cases are:
 
-    PerlIO_binmode(f,ptype,O_BINARY,":raw");
+    PerlIO_binmode(f,ptype,O_BINARY,NULL);
 and
     PerlIO_binmode(f,ptype,O_TEXT,":crlf");
 
@@ -472,13 +507,16 @@ problem.
 PerlIO_debug writes to the file named by $ENV{'PERLIO_DEBUG'} typical
 use might be
 
-  Bourne shells:
+  Bourne shells (sh, ksh, bash, zsh, ash, ...):
    PERLIO_DEBUG=/dev/tty ./perl somescript some args
 
-  Csh:
+  Csh/Tcsh:
    setenv PERLIO_DEBUG /dev/tty
    ./perl somescript some args
 
+  If you have the "env" utility:
+   env PERLIO_DEBUG=/dev/tty ./perl somescript some args
+
   Win32:
    set PERLIO_DEBUG=CON
    perl somescript some args