diff options
Diffstat (limited to 'pod/perlapio.pod')
| -rw-r--r-- | pod/perlapio.pod | 274 |
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 |