diff options
Diffstat (limited to 'contrib/perl5/pod/perlapio.pod')
| -rw-r--r-- | contrib/perl5/pod/perlapio.pod | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/contrib/perl5/pod/perlapio.pod b/contrib/perl5/pod/perlapio.pod deleted file mode 100644 index 90475a9..0000000 --- a/contrib/perl5/pod/perlapio.pod +++ /dev/null @@ -1,274 +0,0 @@ -=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 |
