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.
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)>
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
=item B<PerlIO_importFILE(f,flags)>
-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.
+it a char *mode as in fopen/freopen. Flags are currently ignored, and
+code attempts to empirically determine the mode in which I<f> is open.
+
+Once called the FILE * should I<ONLY> be closed by calling
+C<PerlIO_close()> on the returned PerlIO *.
=item B<PerlIO_exportFILE(f,flags)>
-Given a PerlIO * return a 'native' FILE * suitable for passing to code
+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 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. Flags are ignored and the
+FILE * is opened in same mode as the PerlIO *.
-The fact that such a FILE * has been 'exported' is recorded, and may
-affect future PerlIO operations on the original PerlIO *.
-
-=item B<PerlIO_findFILE(f)>
+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 *.
-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.
+
+=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
=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
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
projects / p5sagit/p5-mst-13.2.git / blobdiff