1=head1 NAME 2 3perlapio - perl's IO abstraction interface. 4 5=head1 SYNOPSIS 6 7 PerlIO *PerlIO_stdin(void); 8 PerlIO *PerlIO_stdout(void); 9 PerlIO *PerlIO_stderr(void); 10 11 PerlIO *PerlIO_open(const char *,const char *); 12 int PerlIO_close(PerlIO *); 13 14 int PerlIO_stdoutf(const char *,...) 15 int PerlIO_puts(PerlIO *,const char *); 16 int PerlIO_putc(PerlIO *,int); 17 int PerlIO_write(PerlIO *,const void *,size_t); 18 int PerlIO_printf(PerlIO *, const char *,...); 19 int PerlIO_vprintf(PerlIO *, const char *, va_list); 20 int PerlIO_flush(PerlIO *); 21 22 int PerlIO_eof(PerlIO *); 23 int PerlIO_error(PerlIO *); 24 void PerlIO_clearerr(PerlIO *); 25 26 int PerlIO_getc(PerlIO *); 27 int PerlIO_ungetc(PerlIO *,int); 28 int PerlIO_read(PerlIO *,void *,size_t); 29 30 int PerlIO_fileno(PerlIO *); 31 PerlIO *PerlIO_fdopen(int, const char *); 32 PerlIO *PerlIO_importFILE(FILE *, int flags); 33 FILE *PerlIO_exportFILE(PerlIO *, int flags); 34 FILE *PerlIO_findFILE(PerlIO *); 35 void PerlIO_releaseFILE(PerlIO *,FILE *); 36 37 void PerlIO_setlinebuf(PerlIO *); 38 39 long PerlIO_tell(PerlIO *); 40 int PerlIO_seek(PerlIO *,off_t,int); 41 int PerlIO_getpos(PerlIO *,Fpos_t *) 42 int PerlIO_setpos(PerlIO *,Fpos_t *) 43 void PerlIO_rewind(PerlIO *); 44 45 int PerlIO_has_base(PerlIO *); 46 int PerlIO_has_cntptr(PerlIO *); 47 int PerlIO_fast_gets(PerlIO *); 48 int PerlIO_canset_cnt(PerlIO *); 49 50 char *PerlIO_get_ptr(PerlIO *); 51 int PerlIO_get_cnt(PerlIO *); 52 void PerlIO_set_cnt(PerlIO *,int); 53 void PerlIO_set_ptrcnt(PerlIO *,char *,int); 54 char *PerlIO_get_base(PerlIO *); 55 int PerlIO_get_bufsiz(PerlIO *); 56 57=head1 DESCRIPTION 58 59Perl's source code should use the above functions instead of those 60defined in ANSI C's I<stdio.h>. The perl headers will C<#define> them to 61the I/O mechanism selected at Configure time. 62 63The functions are modeled on those in I<stdio.h>, but parameter order 64has been "tidied up a little". 65 66=over 4 67 68=item B<PerlIO *> 69 70This takes the place of FILE *. Like FILE * it should be treated as 71opaque (it is probably safe to assume it is a pointer to something). 72 73=item B<PerlIO_stdin()>, B<PerlIO_stdout()>, B<PerlIO_stderr()> 74 75Use these rather than C<stdin>, C<stdout>, C<stderr>. They are written 76to look like "function calls" rather than variables because this makes 77it easier to I<make them> function calls if platform cannot export data 78to loaded modules, or if (say) different "threads" might have different 79values. 80 81=item B<PerlIO_open(path, mode)>, B<PerlIO_fdopen(fd,mode)> 82 83These correspond to fopen()/fdopen() arguments are the same. 84 85=item B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)> 86 87These are fprintf()/vfprintf() equivalents. 88 89=item B<PerlIO_stdoutf(fmt,...)> 90 91This is printf() equivalent. printf is #defined to this function, 92so it is (currently) legal to use C<printf(fmt,...)> in perl sources. 93 94=item B<PerlIO_read(f,buf,count)>, B<PerlIO_write(f,buf,count)> 95 96These correspond to fread() and fwrite(). Note that arguments 97are different, there is only one "count" and order has 98"file" first. 99 100=item B<PerlIO_close(f)> 101 102=item B<PerlIO_puts(f,s)>, B<PerlIO_putc(f,c)> 103 104These correspond to fputs() and fputc(). 105Note that arguments have been revised to have "file" first. 106 107=item B<PerlIO_ungetc(f,c)> 108 109This corresponds to ungetc(). 110Note that arguments have been revised to have "file" first. 111 112=item B<PerlIO_getc(f)> 113 114This corresponds to getc(). 115 116=item B<PerlIO_eof(f)> 117 118This corresponds to feof(). 119 120=item B<PerlIO_error(f)> 121 122This corresponds to ferror(). 123 124=item B<PerlIO_fileno(f)> 125 126This corresponds to fileno(), note that on some platforms, 127the meaning of "fileno" may not match Unix. 128 129=item B<PerlIO_clearerr(f)> 130 131This corresponds to clearerr(), i.e., clears 'eof' and 'error' 132flags for the "stream". 133 134=item B<PerlIO_flush(f)> 135 136This corresponds to fflush(). 137 138=item B<PerlIO_tell(f)> 139 140This corresponds to ftell(). 141 142=item B<PerlIO_seek(f,o,w)> 143 144This corresponds to fseek(). 145 146=item B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)> 147 148These correspond to fgetpos() and fsetpos(). If platform does not 149have the stdio calls then they are implemented in terms of PerlIO_tell() 150and PerlIO_seek(). 151 152=item B<PerlIO_rewind(f)> 153 154This corresponds to rewind(). Note may be redefined 155in terms of PerlIO_seek() at some point. 156 157=item B<PerlIO_tmpfile()> 158 159This corresponds to tmpfile(), i.e., returns an anonymous 160PerlIO which will automatically be deleted when closed. 161 162=back 163 164=head2 Co-existence with stdio 165 166There is outline support for co-existence of PerlIO with stdio. 167Obviously if PerlIO is implemented in terms of stdio there is 168no problem. However if perlio is implemented on top of (say) sfio 169then mechanisms must exist to create a FILE * which can be passed 170to library code which is going to use stdio calls. 171 172=over 4 173 174=item B<PerlIO_importFILE(f,flags)> 175 176Used to get a PerlIO * from a FILE *. 177May need additional arguments, interface under review. 178 179=item B<PerlIO_exportFILE(f,flags)> 180 181Given an PerlIO * return a 'native' FILE * suitable for 182passing to code expecting to be compiled and linked with 183ANSI C I<stdio.h>. 184 185The fact that such a FILE * has been 'exported' is recorded, 186and may affect future PerlIO operations on the original 187PerlIO *. 188 189=item B<PerlIO_findFILE(f)> 190 191Returns previously 'exported' FILE * (if any). 192Place holder until interface is fully defined. 193 194=item B<PerlIO_releaseFILE(p,f)> 195 196Calling PerlIO_releaseFILE informs PerlIO that all use 197of FILE * is complete. It is removed from list of 'exported' 198FILE *s, and associated PerlIO * should revert to original 199behaviour. 200 201=item B<PerlIO_setlinebuf(f)> 202 203This corresponds to setlinebuf(). Use is deprecated pending 204further discussion. (Perl core uses it I<only> when "dumping"; 205it has nothing to do with $| auto-flush.) 206 207=back 208 209In addition to user API above there is an "implementation" interface 210which allows perl to get at internals of PerlIO. 211The following calls correspond to the various FILE_xxx macros determined 212by Configure. This section is really of interest to only those 213concerned with detailed perl-core behaviour or implementing a 214PerlIO mapping. 215 216=over 4 217 218=item B<PerlIO_has_cntptr(f)> 219 220Implementation can return pointer to current position in the "buffer" and 221a count of bytes available in the buffer. 222 223=item B<PerlIO_get_ptr(f)> 224 225Return pointer to next readable byte in buffer. 226 227=item B<PerlIO_get_cnt(f)> 228 229Return count of readable bytes in the buffer. 230 231=item B<PerlIO_canset_cnt(f)> 232 233Implementation can adjust its idea of number of 234bytes in the buffer. 235 236=item B<PerlIO_fast_gets(f)> 237 238Implementation has all the interfaces required to 239allow perl's fast code to handle <FILE> mechanism. 240 241 PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \ 242 PerlIO_canset_cnt(f) && \ 243 `Can set pointer into buffer' 244 245=item B<PerlIO_set_ptrcnt(f,p,c)> 246 247Set pointer into buffer, and a count of bytes still in the 248buffer. Should be used only to set 249pointer to within range implied by previous calls 250to C<PerlIO_get_ptr> and C<PerlIO_get_cnt>. 251 252=item B<PerlIO_set_cnt(f,c)> 253 254Obscure - set count of bytes in the buffer. Deprecated. 255Currently used in only doio.c to force count < -1 to -1. 256Perhaps should be PerlIO_set_empty or similar. 257This call may actually do nothing if "count" is deduced from pointer 258and a "limit". 259 260=item B<PerlIO_has_base(f)> 261 262Implementation has a buffer, and can return pointer 263to whole buffer and its size. Used by perl for B<-T> / B<-B> tests. 264Other uses would be very obscure... 265 266=item B<PerlIO_get_base(f)> 267 268Return I<start> of buffer. 269 270=item B<PerlIO_get_bufsiz(f)> 271 272Return I<total size> of buffer. 273 274=back 275