X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapio.pod;h=90475a9543f4c6f8d8554a68a0543670d80efffc;hb=1f950eb4f39b89f547d5802df0c94526d900d2f2;hp=5d87ff0e05d0def9027302f95e5cf4523f4cca87;hpb=84dc3c4daae48410e767ac41da148ac5c6c45446;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 5d87ff0..90475a9 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -1,22 +1,22 @@ =head1 NAME -perlio - perl's IO abstraction interface. +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_write(PerlIO *,const void *,size_t); int PerlIO_printf(PerlIO *, const char *,...); - int PerlIO_vprintf(PerlIO *, const char *, va_list); + int PerlIO_vprintf(PerlIO *, const char *, va_list); int PerlIO_flush(PerlIO *); int PerlIO_eof(PerlIO *); @@ -25,39 +25,39 @@ perlio - perl's IO abstraction interface. int PerlIO_getc(PerlIO *); int PerlIO_ungetc(PerlIO *,int); - int PerlIO_read(PerlIO *,void *,size_t); + 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 *); + 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 *); + 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 *) + 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 *); + + 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, I will the C<#define> them to +defined in ANSI C's I. The perl headers will C<#define> them to the I/O mechanism selected at Configure time. The functions are modeled on those in I, but parameter order @@ -67,15 +67,15 @@ has been "tidied up a little". =item B -This takes the place of FILE *. Unlike FILE * it should be treated as +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, B, B Use these rather than C, C, C. They are written to look like "function calls" rather than variables because this makes -it easier to I function calls if platform cannot export data -to loaded modules, or if (say) different "threads" might have different +it easier to I function calls if platform cannot export data +to loaded modules, or if (say) different "threads" might have different values. =item B, B @@ -84,7 +84,7 @@ These correspond to fopen()/fdopen() arguments are the same. =item B, B -These are is fprintf()/vfprintf equivalents. +These are fprintf()/vfprintf() equivalents. =item B @@ -93,18 +93,18 @@ so it is (currently) legal to use C in perl sources. =item B, B -These correspond to fread() and fwrite(). Note that arguments +These correspond to fread() and fwrite(). Note that arguments are different, there is only one "count" and order has "file" first. =item B -=item B, B +=item B, B -These correspond to fputs() and fputc(). +These correspond to fputs() and fputc(). Note that arguments have been revised to have "file" first. -=item B +=item B This corresponds to ungetc(). Note that arguments have been revised to have "file" first. @@ -123,12 +123,12 @@ This corresponds to ferror(). =item B -This corresponds to fileno(), note that on some platforms, -the meaning of "fileno" may not match UNIX. +This corresponds to fileno(), note that on some platforms, +the meaning of "fileno" may not match Unix. =item B -This corresponds to clearerr(), i.e. clears 'eof' and 'error' +This corresponds to clearerr(), i.e., clears 'eof' and 'error' flags for the "stream". =item B @@ -145,8 +145,8 @@ This corresponds to fseek(). =item B, B -These correspond to fgetpos() and fsetpos(). If platform does not -have the stdio calls then they are implemeted in terms of PerlIO_tell() +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 @@ -156,17 +156,17 @@ in terms of PerlIO_seek() at some point. =item B -This corresponds to tmpfile(), i.e. returns an anonymous +This corresponds to tmpfile(), i.e., returns an anonymous PerlIO which will automatically be deleted when closed. -=back +=back -=head2 Co-existance with stdio +=head2 Co-existence with stdio -There is outline support for co-existance of PerlIO with stdio. -Obviously if PerlIO is implemented in terms of stdio there is +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 +then mechanisms must exist to create a FILE * which can be passed to library code which is going to use stdio calls. =over 4 @@ -179,12 +179,12 @@ May need additional arguments, interface under review. =item B Given an PerlIO * return a 'native' FILE * suitable for -passing to code expecting to be compiled and linked with +passing to code expecting to be compiled and linked with ANSI C I. The fact that such a FILE * has been 'exported' is recorded, -and may affect future PerlIO operations on the original -PerlIO *. +and may affect future PerlIO operations on the original +PerlIO *. =item B @@ -195,21 +195,21 @@ Place holder until interface is fully defined. 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 +FILE *s, and associated PerlIO * should revert to original behaviour. =item B This corresponds to setlinebuf(). Use is deprecated pending -further discussion. (Perl core I uses it when "dumping" -is has nothing to do with $| auto-flush.) +further discussion. (Perl core uses it I 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 only of interest to those +by Configure. This section is really of interest to only those concerned with detailed perl-core behaviour or implementing a PerlIO mapping. @@ -230,32 +230,32 @@ Return count of readable bytes in the buffer. =item B -Implementation can adjust its idea of number of +Implementation can adjust its idea of number of bytes in the buffer. =item B -Implementation has all the interfaces required to -allow perls fast code to handle mechanism. +Implementation has all the interfaces required to +allow perl's fast code to handle mechanism. - PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ + PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ PerlIO_canset_cnt(f) && \ `Can set pointer into buffer' =item B -Set pointer into buffer, and a count of bytes still in the -buffer. Should only be used to set +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 and C. =item B Obscure - set count of bytes in the buffer. Deprecated. -Currently only used in doio.c to force count < -1 to -1. +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". +and a "limit". =item B @@ -271,4 +271,4 @@ Return I of buffer. Return I of buffer. -=back +=back