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