perl 5.003_02: [no incremental changelog available]

1 files changed, 274 insertions, 0 deletions

diff --git a/pod/perlapio.pod b/pod/perlapio.pod
new file mode 100644
index 0000000000..85900f157c
--- /dev/null
+++ b/pod/perlapio.pod
@@ -0,0 +1,274 @@
+=head1 NAME
+
+perlio - perl's IO abstraction interface.
+
+=head1 SYNOPSIS
+
+    PerlIO *PerlIO_stdin(void);
+    PerlIO *PerlIO_stdout(void);
+    PerlIO *PerlIO_stderr(void);
+    
+    PerlIO *PerlIO_open(const char *,const char *);
+    int     PerlIO_close(PerlIO *);
+
+    int     PerlIO_stdoutf(const char *,...)
+    int     PerlIO_puts(PerlIO *,const char *);
+    int     PerlIO_putc(PerlIO *,int);
+    int     PerlIO_write(PerlIO *,const void *,size_t); 
+    int     PerlIO_printf(PerlIO *, const char *,...);
+    int     PerlIO_vprintf(PerlIO *, const char *, va_list); 
+    int     PerlIO_flush(PerlIO *);
+
+    int     PerlIO_eof(PerlIO *);
+    int     PerlIO_error(PerlIO *);
+    void    PerlIO_clearerr(PerlIO *);
+
+    int     PerlIO_getc(PerlIO *);
+    int     PerlIO_ungetc(PerlIO *,int);
+    int     PerlIO_read(PerlIO *,void *,size_t); 
+
+    int     PerlIO_fileno(PerlIO *);
+    PerlIO *PerlIO_fdopen(int, const char *);
+    PerlIO *PerlIO_importFILE(FILE *);
+    FILE   *PerlIO_exportFILE(PerlIO *);
+    FILE   *PerlIO_findFILE(PerlIO *);
+    void    PerlIO_releaseFILE(PerlIO *,FILE *);
+
+    void    PerlIO_setlinebuf(PerlIO *); 
+
+    long    PerlIO_tell(PerlIO *);
+    int     PerlIO_seek(PerlIO *,off_t,int);
+    int     PerlIO_getpos(PerlIO *,Fpos_t *) 
+    int     PerlIO_setpos(PerlIO *,Fpos_t *) 
+    void    PerlIO_rewind(PerlIO *);
+     
+    int     PerlIO_has_base(PerlIO *); 
+    int     PerlIO_has_cntptr(PerlIO *); 
+    int     PerlIO_fast_gets(PerlIO *); 
+    int     PerlIO_canset_cnt(PerlIO *); 
+
+    char   *PerlIO_get_ptr(PerlIO *); 
+    int     PerlIO_get_cnt(PerlIO *); 
+    void    PerlIO_set_cnt(PerlIO *,int); 
+    void    PerlIO_set_ptrcnt(PerlIO *,char *,int); 
+    char   *PerlIO_get_base(PerlIO *); 
+    int     PerlIO_get_bufsiz(PerlIO *); 
+
+=head1 DESCRIPTION
+
+Perl's source code should use the above functions instead of those
+defined in ANSI C's I<stdio.h>,  I<perlio.h> will the C<#define> them to 
+the I/O mechanism selected at Configure time.
+
+The functions are modeled on those in I<stdio.h>, but parameter order
+has been "tidied up a little".
+
+=over 4
+
+=item B<PerlIO *>
+
+This takes the place of FILE *. Unlike FILE * it should be treated as 
+opaque (it is probably safe to assume it is a pointer to something).
+
+=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()>
+
+Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written
+to look like "function calls" rather than variables because this makes
+it easier to I<make them> function calls if platform cannot export data 
+to loaded modules, or if (say) different "threads" might have different 
+values.
+
+=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)>
+
+These correspond to fopen()/fdopen() arguments are the same.
+
+=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>
+
+These are is fprintf()/vfprintf equivalents.
+
+=item B<PerlIO_stdoutf(fmt,...)>
+
+This is printf() equivalent. printf is #defined to this function,
+so it is (currently) legal to use 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.
+
+=item B<PerlIO_close(f)>
+
+=item B<PerlIO_puts(s,f)>, B<PerlIO_putc(c,f)>
+
+These correspond to fputs() and fputc(). 
+Note that arguments have been revised to have "file" first.
+
+=item B<PerlIO_ungetc(c,f)>
+
+This corresponds to ungetc().
+Note that arguments have been revised to have "file" first.
+
+=item B<PerlIO_getc(f)>
+
+This corresponds to getc().
+
+=item B<PerlIO_eof(f)>
+
+This corresponds to feof().
+
+=item B<PerlIO_error(f)>
+
+This corresponds to ferror().
+
+=item B<PerlIO_fileno(f)>
+
+This corresponds to fileno(), note that on some platforms, 
+the meaning of "fileno" may not match UNIX.
+
+=item B<PerlIO_clearerr(f)>
+
+This corresponds to clearerr(), i.e. clears 'eof' and 'error'
+flags for the "stream".
+
+=item B<PerlIO_flush(f)>
+
+This corresponds to fflush().
+
+=item B<PerlIO_tell(f)>
+
+This corresponds to ftell().
+
+=item B<PerlIO_seek(f,o,w)>
+
+This corresponds to fseek().
+
+=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>
+
+These correspond to fgetpos() and fsetpos(). If platform does not 
+have the stdio calls then they are implemeted in terms of PerlIO_tell()
+and PerlIO_seek().
+
+=item B<PerlIO_rewind(f)>
+
+This corresponds to rewind(). Note may be redefined
+in terms of PerlIO_seek() at some point.
+
+=item B<PerlIO_tmpfile()>
+
+This corresponds to tmpfile(), i.e. returns an anonymous
+PerlIO which will automatically be deleted when closed.
+
+=back 
+
+=head2 Co-existance with stdio
+
+There is outline support for co-existance of PerlIO with stdio.
+Obviously if PerlIO is implemented in terms of stdio there is 
+no problem. However if perlio is implemented on top of (say) sfio
+then mechanisms must exist to create a FILE * which can be passed 
+to library code which is going to use stdio calls.
+
+=over 4
+
+=item B<PerlIO_importFILE(f,flags)>
+
+Used to get a PerlIO * from a FILE *.
+May need additional arguments, interface under review.
+
+=item B<PerlIO_exportFILE(f,flags)>
+
+Given an PerlIO * return a 'native' FILE * suitable for
+passing to code expecting to be compiled and linked with 
+ANSI C I<stdio.h>.
+
+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)>
+
+Returns previously 'exported' FILE * (if any).
+Place holder until interface is fully defined.
+
+=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.
+
+=item B<PerlIO_setlinebuf(f)>
+
+This corresponds to setlinebuf(). Use is deprecated pending
+further discussion. (Perl core I<only> uses it when "dumping"
+is has nothing to do with $| auto-flush.)
+
+=back
+
+In addition to user API above there is an "implementation" interface
+which allows perl to get at internals of PerlIO.
+The following calls correspond to the various FILE_xxx macros determined
+by Configure. This section is really only of interest to those
+concerned with detailed perl-core behaviour or implementing a
+PerlIO mapping.
+
+=over 4
+
+=item B<PerlIO_has_cntptr(f)>
+
+Implementation can return pointer to current position in the "buffer" and
+a count of bytes available in the buffer.
+
+=item B<PerlIO_get_ptr(f)>
+
+Return pointer to next readable byte in buffer.
+
+=item B<PerlIO_get_cnt(f)>
+
+Return count of readable bytes in the buffer.
+
+=item B<PerlIO_canset_cnt(f)>
+
+Implementation can adjust its idea of number of 
+bytes in the buffer.
+
+=item B<PerlIO_fast_gets(f)>
+
+Implementation has all the interfaces required to 
+allow perls fast code to handle <FILE> mechanism.
+
+  PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ 
+                        PerlIO_canset_cnt(f) && \
+                        `Can set pointer into buffer'
+
+=item B<PerlIO_set_ptrcnt(f,p,c)>
+
+Set pointer into buffer, and a count of bytes still in the 
+buffer. Should only be used to set
+pointer to within range implied by previous calls
+to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>.
+
+=item B<PerlIO_set_cnt(f,c)>
+
+Obscure - set count of bytes in the buffer. Deprecated.
+Currently only used in doio.c to force count < -1 to -1.
+Perhaps should be PerlIO_set_empty or similar.
+This call may actually do nothing if "count" is deduced from pointer
+and a "limit". 
+
+=item B<PerlIO_has_base(f)>
+
+Implementation has a buffer, and can return pointer
+to whole buffer and its size. Used by perl for B<-T> / B<-B> tests.
+Other uses would be very obscure...
+
+=item B<PerlIO_get_base(f)>
+
+Return I<start> of buffer.
+
+=item B<PerlIO_get_bufsiz(f)>
+
+Return I<total size> of buffer.
+
+=back