PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)


NAME
       perlapio - perl's IO abstraction interface.



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 *, int flags);
           FILE   *PerlIO_exportFILE(PerlIO *, int flags);
           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 *);




29/Apr/1999            perl 5.005, patch 03                     1





PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)


DESCRIPTION
       Perl's source code should use the above functions instead
       of those defined in ANSI C's stdio.h.  The perl headers
       will #define them to the I/O mechanism selected at
       Configure time.

       The functions are modeled on those in stdio.h, but
       parameter order has been "tidied up a little".

       PerlIO *
           This takes the place of FILE *. Like FILE * it should
           be treated as opaque (it is probably safe to assume it
           is a pointer to something).

       PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()
           Use these rather than stdin, stdout, stderr. They are
           written to look like "function calls" rather than
           variables because this makes it easier to make them
           function calls if platform cannot export data to
           loaded modules, or if (say) different "threads" might
           have different values.

       PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)
           These correspond to fopen()/fdopen() arguments are the
           same.

       PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)
           These are fprintf()/vfprintf() equivalents.

       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.

       PerlIO_read(f,buf,count), 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.

       PerlIO_close(f)

       PerlIO_puts(f,s), PerlIO_putc(f,c)
           These correspond to fputs() and fputc().  Note that
           arguments have been revised to have "file" first.

       PerlIO_ungetc(f,c)
           This corresponds to ungetc().  Note that arguments
           have been revised to have "file" first.

       PerlIO_getc(f)
           This corresponds to getc().

       PerlIO_eof(f)
           This corresponds to feof().



29/Apr/1999            perl 5.005, patch 03                     2





PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)


       PerlIO_error(f)
           This corresponds to ferror().

       PerlIO_fileno(f)
           This corresponds to fileno(), note that on some
           platforms, the meaning of "fileno" may not match Unix.

       PerlIO_clearerr(f)
           This corresponds to clearerr(), i.e., clears 'eof' and
           'error' flags for the "stream".

       PerlIO_flush(f)
           This corresponds to fflush().

       PerlIO_tell(f)
           This corresponds to ftell().

       PerlIO_seek(f,o,w)
           This corresponds to fseek().

       PerlIO_getpos(f,p), PerlIO_setpos(f,p)
           These correspond to fgetpos() and fsetpos(). If
           platform does not have the stdio calls then they are
           implemented in terms of PerlIO_tell() and
           PerlIO_seek().

       PerlIO_rewind(f)
           This corresponds to rewind(). Note may be redefined in
           terms of PerlIO_seek() at some point.

       PerlIO_tmpfile()
           This corresponds to tmpfile(), i.e., returns an
           anonymous PerlIO which will automatically be deleted
           when closed.

       Co-existence with stdio

       There is outline support for co-existence 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.

       PerlIO_importFILE(f,flags)
           Used to get a PerlIO * from a FILE *.  May need
           additional arguments, interface under review.

       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 stdio.h.

           The fact that such a FILE * has been 'exported' is



29/Apr/1999            perl 5.005, patch 03                     3





PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)


           recorded, and may affect future PerlIO operations on
           the original PerlIO *.

       PerlIO_findFILE(f)
           Returns previously 'exported' FILE * (if any).  Place
           holder until interface is fully defined.

       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.

       PerlIO_setlinebuf(f)
           This corresponds to setlinebuf(). Use is deprecated
           pending further discussion. (Perl core uses it only
           when "dumping"; it has nothing to do with $| auto-
           flush.)

       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 of
       interest to only those concerned with detailed perl-core
       behaviour or implementing a PerlIO mapping.

       PerlIO_has_cntptr(f)
           Implementation can return pointer to current position
           in the "buffer" and a count of bytes available in the
           buffer.

       PerlIO_get_ptr(f)
           Return pointer to next readable byte in buffer.

       PerlIO_get_cnt(f)
           Return count of readable bytes in the buffer.

       PerlIO_canset_cnt(f)
           Implementation can adjust its idea of number of bytes
           in the buffer.

       PerlIO_fast_gets(f)
           Implementation has all the interfaces required to
           allow perl's fast code to handle <FILE> mechanism.

             PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
                                   PerlIO_canset_cnt(f) && \
                                   `Can set pointer into buffer'


       PerlIO_set_ptrcnt(f,p,c)
           Set pointer into buffer, and a count of bytes still in
           the buffer. Should be used only to set pointer to
           within range implied by previous calls to



29/Apr/1999            perl 5.005, patch 03                     4





PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)


           PerlIO_get_ptr and PerlIO_get_cnt.

       PerlIO_set_cnt(f,c)
           Obscure - set count of bytes in the buffer.
           Deprecated.  Currently used in only 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".

       PerlIO_has_base(f)
           Implementation has a buffer, and can return pointer to
           whole buffer and its size. Used by perl for -T / -B
           tests.  Other uses would be very obscure...

       PerlIO_get_base(f)
           Return start of buffer.

       PerlIO_get_bufsiz(f)
           Return total size of buffer.






































29/Apr/1999            perl 5.005, patch 03                     5





PERLAPIO(1)      Perl Programmers Reference Guide     PERLAPIO(1)



























































29/Apr/1999            perl 5.005, patch 03                     6