275 lines
7.6 KiB
Plaintext
275 lines
7.6 KiB
Plaintext
|
=head1 NAME
|
||
|
|
|
||
|
|
perlapio - 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 *, 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 *);
|
||
|
|
|
||
|
|
=head1 DESCRIPTION
|
||
|
|
|
||
|
|
Perl's source code should use the above functions instead of those
|
||
|
|
defined in ANSI C's I<stdio.h>. The perl headers will 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 *. Like 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 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 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.
|
||
|
|
|
||
|
|
=item B<PerlIO_close(f)>
|
||
|
|
|
||
|
|
=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)>
|
||
|
|
|
||
|
|
These correspond to fputs() and fputc().
|
||
|
|
Note that arguments have been revised to have "file" first.
|
||
|
|
|
||
|
|
=item B<PerlIO_ungetc(f,c)>
|
||
|
|
|
||
|
|
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 implemented 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-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.
|
||
|
|
|
||
|
|
=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 uses it I<only> when "dumping";
|
||
|
|
it 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 of interest to only 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 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'
|
||
|
|
|
||
|
|
=item B<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 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 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".
|
||
|
|
|
||
|
|
=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
|