| 1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
| 6 | .br |
| 7 | .if t .Sp |
| 8 | .ne 5 |
| 9 | .PP |
| 10 | \fB\\$1\fR |
| 11 | .PP |
| 12 | .. |
| 13 | .de Sp \" Vertical space (when we can't use .PP) |
| 14 | .if t .sp .5v |
| 15 | .if n .sp |
| 16 | .. |
| 17 | .de Vb \" Begin verbatim text |
| 18 | .ft CW |
| 19 | .nf |
| 20 | .ne \\$1 |
| 21 | .. |
| 22 | .de Ve \" End verbatim text |
| 23 | .ft R |
| 24 | .fi |
| 25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
| 29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| 30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| 31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| 32 | .tr \(*W-|\(bv\*(Tr |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
| 36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 39 | . ds L" "" |
| 40 | . ds R" "" |
| 41 | . ds C` "" |
| 42 | . ds C' "" |
| 43 | 'br\} |
| 44 | .el\{\ |
| 45 | . ds -- \|\(em\| |
| 46 | . ds PI \(*p |
| 47 | . ds L" `` |
| 48 | . ds R" '' |
| 49 | 'br\} |
| 50 | .\" |
| 51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| 53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 54 | .\" output yourself in some meaningful fashion. |
| 55 | .if \nF \{\ |
| 56 | . de IX |
| 57 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 58 | .. |
| 59 | . nr % 0 |
| 60 | . rr F |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 64 | .\" way too many mistakes in technical documents. |
| 65 | .hy 0 |
| 66 | .if n .na |
| 67 | .\" |
| 68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 70 | . \" fudge factors for nroff and troff |
| 71 | .if n \{\ |
| 72 | . ds #H 0 |
| 73 | . ds #V .8m |
| 74 | . ds #F .3m |
| 75 | . ds #[ \f1 |
| 76 | . ds #] \fP |
| 77 | .\} |
| 78 | .if t \{\ |
| 79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 80 | . ds #V .6m |
| 81 | . ds #F 0 |
| 82 | . ds #[ \& |
| 83 | . ds #] \& |
| 84 | .\} |
| 85 | . \" simple accents for nroff and troff |
| 86 | .if n \{\ |
| 87 | . ds ' \& |
| 88 | . ds ` \& |
| 89 | . ds ^ \& |
| 90 | . ds , \& |
| 91 | . ds ~ ~ |
| 92 | . ds / |
| 93 | .\} |
| 94 | .if t \{\ |
| 95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 101 | .\} |
| 102 | . \" troff and (daisy-wheel) nroff accents |
| 103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 110 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 112 | . \" corrections for vroff |
| 113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 115 | . \" for low resolution devices (crt and lpr) |
| 116 | .if \n(.H>23 .if \n(.V>19 \ |
| 117 | \{\ |
| 118 | . ds : e |
| 119 | . ds 8 ss |
| 120 | . ds o a |
| 121 | . ds d- d\h'-1'\(ga |
| 122 | . ds D- D\h'-1'\(hy |
| 123 | . ds th \o'bp' |
| 124 | . ds Th \o'LP' |
| 125 | . ds ae ae |
| 126 | . ds Ae AE |
| 127 | .\} |
| 128 | .rm #[ #] #H #V #F C |
| 129 | .\" ======================================================================== |
| 130 | .\" |
| 131 | .IX Title "PERLAPIO 1" |
| 132 | .TH PERLAPIO 1 "2002-06-08" "perl v5.8.0" "Perl Programmers Reference Guide" |
| 133 | .SH "NAME" |
| 134 | perlapio \- perl's IO abstraction interface. |
| 135 | .SH "SYNOPSIS" |
| 136 | .IX Header "SYNOPSIS" |
| 137 | .Vb 2 |
| 138 | \& #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */ |
| 139 | \& #include <perlio.h> /* Usually via #include <perl.h> */ |
| 140 | .Ve |
| 141 | .PP |
| 142 | .Vb 3 |
| 143 | \& PerlIO *PerlIO_stdin(void); |
| 144 | \& PerlIO *PerlIO_stdout(void); |
| 145 | \& PerlIO *PerlIO_stderr(void); |
| 146 | .Ve |
| 147 | .PP |
| 148 | .Vb 4 |
| 149 | \& PerlIO *PerlIO_open(const char *path,const char *mode); |
| 150 | \& PerlIO *PerlIO_fdopen(int fd, const char *mode); |
| 151 | \& PerlIO *PerlIO_reopen(const char *path, const char *mode, PerlIO *old); /* deprecated */ |
| 152 | \& int PerlIO_close(PerlIO *f); |
| 153 | .Ve |
| 154 | .PP |
| 155 | .Vb 7 |
| 156 | \& int PerlIO_stdoutf(const char *fmt,...) |
| 157 | \& int PerlIO_puts(PerlIO *f,const char *string); |
| 158 | \& int PerlIO_putc(PerlIO *f,int ch); |
| 159 | \& int PerlIO_write(PerlIO *f,const void *buf,size_t numbytes); |
| 160 | \& int PerlIO_printf(PerlIO *f, const char *fmt,...); |
| 161 | \& int PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args); |
| 162 | \& int PerlIO_flush(PerlIO *f); |
| 163 | .Ve |
| 164 | .PP |
| 165 | .Vb 3 |
| 166 | \& int PerlIO_eof(PerlIO *f); |
| 167 | \& int PerlIO_error(PerlIO *f); |
| 168 | \& void PerlIO_clearerr(PerlIO *f); |
| 169 | .Ve |
| 170 | .PP |
| 171 | .Vb 3 |
| 172 | \& int PerlIO_getc(PerlIO *d); |
| 173 | \& int PerlIO_ungetc(PerlIO *f,int ch); |
| 174 | \& int PerlIO_read(PerlIO *f, void *buf, size_t numbytes); |
| 175 | .Ve |
| 176 | .PP |
| 177 | .Vb 1 |
| 178 | \& int PerlIO_fileno(PerlIO *f); |
| 179 | .Ve |
| 180 | .PP |
| 181 | .Vb 1 |
| 182 | \& void PerlIO_setlinebuf(PerlIO *f); |
| 183 | .Ve |
| 184 | .PP |
| 185 | .Vb 3 |
| 186 | \& Off_t PerlIO_tell(PerlIO *f); |
| 187 | \& int PerlIO_seek(PerlIO *f, Off_t offset, int whence); |
| 188 | \& void PerlIO_rewind(PerlIO *f); |
| 189 | .Ve |
| 190 | .PP |
| 191 | .Vb 2 |
| 192 | \& int PerlIO_getpos(PerlIO *f, SV *save); /* prototype changed */ |
| 193 | \& int PerlIO_setpos(PerlIO *f, SV *saved); /* prototype changed */ |
| 194 | .Ve |
| 195 | .PP |
| 196 | .Vb 5 |
| 197 | \& int PerlIO_fast_gets(PerlIO *f); |
| 198 | \& int PerlIO_has_cntptr(PerlIO *f); |
| 199 | \& int PerlIO_get_cnt(PerlIO *f); |
| 200 | \& char *PerlIO_get_ptr(PerlIO *f); |
| 201 | \& void PerlIO_set_ptrcnt(PerlIO *f, char *ptr, int count); |
| 202 | .Ve |
| 203 | .PP |
| 204 | .Vb 2 |
| 205 | \& int PerlIO_canset_cnt(PerlIO *f); /* deprecated */ |
| 206 | \& void PerlIO_set_cnt(PerlIO *f, int count); /* deprecated */ |
| 207 | .Ve |
| 208 | .PP |
| 209 | .Vb 3 |
| 210 | \& int PerlIO_has_base(PerlIO *f); |
| 211 | \& char *PerlIO_get_base(PerlIO *f); |
| 212 | \& int PerlIO_get_bufsiz(PerlIO *f); |
| 213 | .Ve |
| 214 | .PP |
| 215 | .Vb 4 |
| 216 | \& PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode); |
| 217 | \& FILE *PerlIO_exportFILE(PerlIO *f, int flags); |
| 218 | \& FILE *PerlIO_findFILE(PerlIO *f); |
| 219 | \& void PerlIO_releaseFILE(PerlIO *f,FILE *stdio); |
| 220 | .Ve |
| 221 | .PP |
| 222 | .Vb 3 |
| 223 | \& int PerlIO_apply_layers(PerlIO *f, const char *mode, const char *layers); |
| 224 | \& int PerlIO_binmode(PerlIO *f, int ptype, int imode, const char *layers); |
| 225 | \& void PerlIO_debug(const char *fmt,...) |
| 226 | .Ve |
| 227 | .SH "DESCRIPTION" |
| 228 | .IX Header "DESCRIPTION" |
| 229 | Perl's source code, and extensions that want maximum portability, |
| 230 | should use the above functions instead of those defined in \s-1ANSI\s0 C's |
| 231 | \&\fIstdio.h\fR. The perl headers (in particular \*(L"perlio.h\*(R") will |
| 232 | \&\f(CW\*(C`#define\*(C'\fR them to the I/O mechanism selected at Configure time. |
| 233 | .PP |
| 234 | The functions are modeled on those in \fIstdio.h\fR, but parameter order |
| 235 | has been \*(L"tidied up a little\*(R". |
| 236 | .PP |
| 237 | \&\f(CW\*(C`PerlIO *\*(C'\fR takes the place of \s-1FILE\s0 *. Like \s-1FILE\s0 * it should be |
| 238 | treated as opaque (it is probably safe to assume it is a pointer to |
| 239 | something). |
| 240 | .PP |
| 241 | There are currently three implementations: |
| 242 | .IP "1. \s-1USE_STDIO\s0" 4 |
| 243 | .IX Item "1. USE_STDIO" |
| 244 | All above are #define'd to stdio functions or are trivial wrapper |
| 245 | functions which call stdio. In this case \fIonly\fR PerlIO * is a \s-1FILE\s0 *. |
| 246 | This has been the default implementation since the abstraction was |
| 247 | introduced in perl5.003_02. |
| 248 | .IP "2. \s-1USE_SFIO\s0" 4 |
| 249 | .IX Item "2. USE_SFIO" |
| 250 | A \*(L"legacy\*(R" implementation in terms of the \*(L"sfio\*(R" library. Used for |
| 251 | some specialist applications on Unix machines (\*(L"sfio\*(R" is not widely |
| 252 | ported away from Unix). Most of above are #define'd to the sfio |
| 253 | functions. PerlIO * is in this case Sfio_t *. |
| 254 | .IP "3. \s-1USE_PERLIO\s0" 4 |
| 255 | .IX Item "3. USE_PERLIO" |
| 256 | Introduced just after perl5.7.0, this is a re-implementation of the |
| 257 | above abstraction which allows perl more control over how \s-1IO\s0 is done |
| 258 | as it decouples \s-1IO\s0 from the way the operating system and C library |
| 259 | choose to do things. For \s-1USE_PERLIO\s0 PerlIO * has an extra layer of |
| 260 | indirection \- it is a pointer\-to\-a\-pointer. This allows the PerlIO * |
| 261 | to remain with a known value while swapping the implementation around |
| 262 | underneath \fIat run time\fR. In this case all the above are true (but |
| 263 | very simple) functions which call the underlying implementation. |
| 264 | .Sp |
| 265 | This is the only implementation for which \f(CW\*(C`PerlIO_apply_layers()\*(C'\fR |
| 266 | does anything \*(L"interesting\*(R". |
| 267 | .Sp |
| 268 | The \s-1USE_PERLIO\s0 implementation is described in perliol. |
| 269 | .PP |
| 270 | Because \*(L"perlio.h\*(R" is a thin layer (for efficiency) the semantics of |
| 271 | these functions are somewhat dependent on the underlying implementation. |
| 272 | Where these variations are understood they are noted below. |
| 273 | .PP |
| 274 | Unless otherwise noted, functions return 0 on success, or a negative |
| 275 | value (usually \f(CW\*(C`EOF\*(C'\fR which is usually \-1) and set \f(CW\*(C`errno\*(C'\fR on error. |
| 276 | .IP "\fB\f(BIPerlIO_stdin()\fB\fR, \fB\f(BIPerlIO_stdout()\fB\fR, \fB\f(BIPerlIO_stderr()\fB\fR" 4 |
| 277 | .IX Item "PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()" |
| 278 | Use these rather than \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, \f(CW\*(C`stderr\*(C'\fR. They are written |
| 279 | to look like \*(L"function calls\*(R" rather than variables because this makes |
| 280 | it easier to \fImake them\fR function calls if platform cannot export data |
| 281 | to loaded modules, or if (say) different \*(L"threads\*(R" might have different |
| 282 | values. |
| 283 | .IP "\fBPerlIO_open(path, mode)\fR, \fBPerlIO_fdopen(fd,mode)\fR" 4 |
| 284 | .IX Item "PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)" |
| 285 | These correspond to \fIfopen()\fR/\fIfdopen()\fR and the arguments are the same. |
| 286 | Return \f(CW\*(C`NULL\*(C'\fR and set \f(CW\*(C`errno\*(C'\fR if there is an error. There may be an |
| 287 | implementation limit on the number of open handles, which may be lower |
| 288 | than the limit on the number of open files \- \f(CW\*(C`errno\*(C'\fR may not be set |
| 289 | when \f(CW\*(C`NULL\*(C'\fR is returned if this limit is exceeded. |
| 290 | .IP "\fBPerlIO_reopen(path,mode,f)\fR" 4 |
| 291 | .IX Item "PerlIO_reopen(path,mode,f)" |
| 292 | While this currently exists in all three implementations perl itself |
| 293 | does not use it. \fIAs perl does not use it, it is not well tested.\fR |
| 294 | .Sp |
| 295 | Perl prefers to \f(CW\*(C`dup\*(C'\fR the new low-level descriptor to the descriptor |
| 296 | used by the existing PerlIO. This may become the behaviour of this |
| 297 | function in the future. |
| 298 | .IP "\fBPerlIO_printf(f,fmt,...)\fR, \fBPerlIO_vprintf(f,fmt,a)\fR" 4 |
| 299 | .IX Item "PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)" |
| 300 | These are \fIfprintf()\fR/\fIvfprintf()\fR equivalents. |
| 301 | .IP "\fBPerlIO_stdoutf(fmt,...)\fR" 4 |
| 302 | .IX Item "PerlIO_stdoutf(fmt,...)" |
| 303 | This is \fIprintf()\fR equivalent. printf is #defined to this function, |
| 304 | so it is (currently) legal to use \f(CW\*(C`printf(fmt,...)\*(C'\fR in perl sources. |
| 305 | .IP "\fBPerlIO_read(f,buf,count)\fR, \fBPerlIO_write(f,buf,count)\fR" 4 |
| 306 | .IX Item "PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)" |
| 307 | These correspond to \fIfread()\fR and \fIfwrite()\fR. Note that arguments are |
| 308 | different, there is only one \*(L"count\*(R" and order has \*(L"file\*(R" |
| 309 | first. Returns a byte count if successful (which may be zero or positive), returns |
| 310 | negative value and sets \f(CW\*(C`errno\*(C'\fR on error. Depending on |
| 311 | implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was interrupted |
| 312 | by a signal. |
| 313 | .IP "\fBPerlIO_close(f)\fR" 4 |
| 314 | .IX Item "PerlIO_close(f)" |
| 315 | Depending on implementation \f(CW\*(C`errno\*(C'\fR may be \f(CW\*(C`EINTR\*(C'\fR if operation was |
| 316 | interrupted by a signal. |
| 317 | .IP "\fBPerlIO_puts(f,s)\fR, \fBPerlIO_putc(f,c)\fR" 4 |
| 318 | .IX Item "PerlIO_puts(f,s), PerlIO_putc(f,c)" |
| 319 | These correspond to \fIfputs()\fR and \fIfputc()\fR. |
| 320 | Note that arguments have been revised to have \*(L"file\*(R" first. |
| 321 | .IP "\fBPerlIO_ungetc(f,c)\fR" 4 |
| 322 | .IX Item "PerlIO_ungetc(f,c)" |
| 323 | This corresponds to \fIungetc()\fR. Note that arguments have been revised |
| 324 | to have \*(L"file\*(R" first. Arranges that next read operation will return |
| 325 | the byte \fBc\fR. Despite the implied \*(L"character\*(R" in the name only |
| 326 | values in the range 0..0xFF are defined. Returns the byte \fBc\fR on |
| 327 | success or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error. The number of bytes that can be |
| 328 | \&\*(L"pushed back\*(R" may vary, only 1 character is certain, and then only if |
| 329 | it is the last character that was read from the handle. |
| 330 | .IP "\fBPerlIO_getc(f)\fR" 4 |
| 331 | .IX Item "PerlIO_getc(f)" |
| 332 | This corresponds to \fIgetc()\fR. |
| 333 | Despite the c in the name only byte range 0..0xFF is supported. |
| 334 | Returns the character read or \-1 (\f(CW\*(C`EOF\*(C'\fR) on error. |
| 335 | .IP "\fBPerlIO_eof(f)\fR" 4 |
| 336 | .IX Item "PerlIO_eof(f)" |
| 337 | This corresponds to \fIfeof()\fR. Returns a true/false indication of |
| 338 | whether the handle is at end of file. For terminal devices this may |
| 339 | or may not be \*(L"sticky\*(R" depending on the implementation. The flag is |
| 340 | cleared by \fIPerlIO_seek()\fR, or \fIPerlIO_rewind()\fR. |
| 341 | .IP "\fBPerlIO_error(f)\fR" 4 |
| 342 | .IX Item "PerlIO_error(f)" |
| 343 | This corresponds to \fIferror()\fR. Returns a true/false indication of |
| 344 | whether there has been an \s-1IO\s0 error on the handle. |
| 345 | .IP "\fBPerlIO_fileno(f)\fR" 4 |
| 346 | .IX Item "PerlIO_fileno(f)" |
| 347 | This corresponds to \fIfileno()\fR, note that on some platforms, the meaning |
| 348 | of \*(L"fileno\*(R" may not match Unix. Returns \-1 if the handle has no open |
| 349 | descriptor associated with it. |
| 350 | .IP "\fBPerlIO_clearerr(f)\fR" 4 |
| 351 | .IX Item "PerlIO_clearerr(f)" |
| 352 | This corresponds to \fIclearerr()\fR, i.e., clears 'error' and (usually) |
| 353 | \&'eof' flags for the \*(L"stream\*(R". Does not return a value. |
| 354 | .IP "\fBPerlIO_flush(f)\fR" 4 |
| 355 | .IX Item "PerlIO_flush(f)" |
| 356 | This corresponds to \fIfflush()\fR. Sends any buffered write data to the |
| 357 | underlying file. If called with \f(CW\*(C`NULL\*(C'\fR this may flush all open |
| 358 | streams (or core dump with some \s-1USE_STDIO\s0 implementattions). |
| 359 | Calling on a handle open for read only, or on which last operation was a read of some kind |
| 360 | may lead to undefined behaviour on some \s-1USE_STDIO\s0 implementations. |
| 361 | The \s-1USE_PERLIO\s0 (layers) implementation tries to behave better: it flushes all open streams |
| 362 | when passed \f(CW\*(C`NULL\*(C'\fR, and attempts to retain data on read streams either in the buffer |
| 363 | or by seeking the handle to the current logical position. |
| 364 | .IP "\fBPerlIO_seek(f,offset,whence)\fR" 4 |
| 365 | .IX Item "PerlIO_seek(f,offset,whence)" |
| 366 | This corresponds to \fIfseek()\fR. Sends buffered write data to the |
| 367 | underlying file, or discards any buffered read data, then positions |
| 368 | the file desciptor as specified by \fBoffset\fR and \fBwhence\fR (sic). |
| 369 | This is the correct thing to do when switching between read and write |
| 370 | on the same handle (see issues with \fIPerlIO_flush()\fR above). Offset is |
| 371 | of type \f(CW\*(C`Off_t\*(C'\fR which is a perl Configure value which may not be same |
| 372 | as stdio's \f(CW\*(C`off_t\*(C'\fR. |
| 373 | .IP "\fBPerlIO_tell(f)\fR" 4 |
| 374 | .IX Item "PerlIO_tell(f)" |
| 375 | This corresponds to \fIftell()\fR. Returns the current file position, or |
| 376 | (Off_t) \-1 on error. May just return value system \*(L"knows\*(R" without |
| 377 | making a system call or checking the underlying file descriptor (so |
| 378 | use on shared file descriptors is not safe without a |
| 379 | \&\fIPerlIO_seek()\fR). Return value is of type \f(CW\*(C`Off_t\*(C'\fR which is a perl |
| 380 | Configure value which may not be same as stdio's \f(CW\*(C`off_t\*(C'\fR. |
| 381 | .IP "\fBPerlIO_getpos(f,p)\fR, \fBPerlIO_setpos(f,p)\fR" 4 |
| 382 | .IX Item "PerlIO_getpos(f,p), PerlIO_setpos(f,p)" |
| 383 | These correspond (loosely) to \fIfgetpos()\fR and \fIfsetpos()\fR. Rather than |
| 384 | stdio's Fpos_t they expect a \*(L"Perl Scalar Value\*(R" to be passed. What is |
| 385 | stored there should be considered opaque. The layout of the data may |
| 386 | vary from handle to handle. When not using stdio or if platform does |
| 387 | not have the stdio calls then they are implemented in terms of |
| 388 | \&\fIPerlIO_tell()\fR and \fIPerlIO_seek()\fR. |
| 389 | .IP "\fBPerlIO_rewind(f)\fR" 4 |
| 390 | .IX Item "PerlIO_rewind(f)" |
| 391 | This corresponds to \fIrewind()\fR. It is usually defined as being |
| 392 | .Sp |
| 393 | .Vb 2 |
| 394 | \& PerlIO_seek(f,(Off_t)0L, SEEK_SET); |
| 395 | \& PerlIO_clearerr(f); |
| 396 | .Ve |
| 397 | .IP "\fB\f(BIPerlIO_tmpfile()\fB\fR" 4 |
| 398 | .IX Item "PerlIO_tmpfile()" |
| 399 | This corresponds to \fItmpfile()\fR, i.e., returns an anonymous PerlIO or |
| 400 | \&\s-1NULL\s0 on error. The system will attempt to automatically delete the |
| 401 | file when closed. On Unix the file is usually \f(CW\*(C`unlink\*(C'\fR\-ed just after |
| 402 | it is created so it does not matter how it gets closed. On other |
| 403 | systems the file may only be deleted if closed via \fIPerlIO_close()\fR |
| 404 | and/or the program exits via \f(CW\*(C`exit\*(C'\fR. Depending on the implementation |
| 405 | there may be \*(L"race conditions\*(R" which allow other processes access to |
| 406 | the file, though in general it will be safer in this regard than |
| 407 | ad. hoc. schemes. |
| 408 | .IP "\fBPerlIO_setlinebuf(f)\fR" 4 |
| 409 | .IX Item "PerlIO_setlinebuf(f)" |
| 410 | This corresponds to \fIsetlinebuf()\fR. Does not return a value. What |
| 411 | constitutes a \*(L"line\*(R" is implementation dependent but usually means |
| 412 | that writing \*(L"\en\*(R" flushes the buffer. What happens with things like |
| 413 | \&\*(L"this\enthat\*(R" is uncertain. (Perl core uses it \fIonly\fR when \*(L"dumping\*(R"; |
| 414 | it has nothing to do with $| auto\-flush.) |
| 415 | .Sh "Co-existence with stdio" |
| 416 | .IX Subsection "Co-existence with stdio" |
| 417 | There is outline support for co-existence of PerlIO with stdio. |
| 418 | Obviously if PerlIO is implemented in terms of stdio there is no |
| 419 | problem. However in other cases then mechanisms must exist to create a |
| 420 | \&\s-1FILE\s0 * which can be passed to library code which is going to use stdio |
| 421 | calls. |
| 422 | .PP |
| 423 | The first step is to add this line: |
| 424 | .PP |
| 425 | .Vb 1 |
| 426 | \& #define PERLIO_NOT_STDIO 0 |
| 427 | .Ve |
| 428 | .PP |
| 429 | \&\fIbefore\fR including any perl header files. (This will probably become |
| 430 | the default at some point). That prevents \*(L"perlio.h\*(R" from attempting |
| 431 | to #define stdio functions onto PerlIO functions. |
| 432 | .PP |
| 433 | \&\s-1XS\s0 code is probably better using \*(L"typemap\*(R" if it expects \s-1FILE\s0 * |
| 434 | arguments. The standard typemap will be adjusted to comprehend any |
| 435 | changes in this area. |
| 436 | .IP "\fBPerlIO_importFILE(f,mode)\fR" 4 |
| 437 | .IX Item "PerlIO_importFILE(f,mode)" |
| 438 | Used to get a PerlIO * from a \s-1FILE\s0 *. |
| 439 | .Sp |
| 440 | The mode argument should be a string as would be passed to fopen/PerlIO_open. |
| 441 | If it is \s-1NULL\s0 then \- for legacy support \- the code will (depending upon |
| 442 | the platform and the implementation) either attempt to empirically determine the mode in |
| 443 | which \fIf\fR is open, or use \*(L"r+\*(R" to indicate a read/write stream. |
| 444 | .Sp |
| 445 | Once called the \s-1FILE\s0 * should \fI\s-1ONLY\s0\fR be closed by calling |
| 446 | \&\f(CW\*(C`PerlIO_close()\*(C'\fR on the returned PerlIO *. |
| 447 | .Sp |
| 448 | The PerlIO is set to textmode. Use PerlIO_binmode if this is |
| 449 | not the desired mode. |
| 450 | .Sp |
| 451 | This is \fBnot\fR the reverse of \fIPerlIO_exportFILE()\fR. |
| 452 | .IP "\fBPerlIO_exportFILE(f,mode)\fR" 4 |
| 453 | .IX Item "PerlIO_exportFILE(f,mode)" |
| 454 | Given a PerlIO * create a 'native' \s-1FILE\s0 * suitable for passing to code |
| 455 | expecting to be compiled and linked with \s-1ANSI\s0 C \fIstdio.h\fR. |
| 456 | The mode argument should be a string as would be passed to fopen/PerlIO_open. |
| 457 | If it is \s-1NULL\s0 then \- for legacy support \- the \s-1FILE\s0 * is opened |
| 458 | in same mode as the PerlIO *. |
| 459 | .Sp |
| 460 | The fact that such a \s-1FILE\s0 * has been 'exported' is recorded, (normally by |
| 461 | pushing a new :stdio \*(L"layer\*(R" onto the PerlIO *), which may affect future |
| 462 | PerlIO operations on the original PerlIO *. |
| 463 | You should not call \f(CW\*(C`fclose()\*(C'\fR on the file unless you call |
| 464 | \&\f(CW\*(C`PerlIO_releaseFILE()\*(C'\fR to disassociate it from the PerlIO *. |
| 465 | (Do not use \fIPerlIO_importFILE()\fR for doing the disassociation.) |
| 466 | .Sp |
| 467 | Calling this function repeatedly will create a \s-1FILE\s0 * on each call |
| 468 | (and will push an :stdio layer each time as well). |
| 469 | .IP "\fBPerlIO_releaseFILE(p,f)\fR" 4 |
| 470 | .IX Item "PerlIO_releaseFILE(p,f)" |
| 471 | Calling PerlIO_releaseFILE informs PerlIO that all use of \s-1FILE\s0 * is |
| 472 | complete. It is removed from the list of 'exported' \s-1FILE\s0 *s, and the |
| 473 | associated PerlIO * should revert to its original behaviour. |
| 474 | .Sp |
| 475 | Use this to disassociate a file from a PerlIO * that was associated |
| 476 | using \fIPerlIO_exportFILE()\fR. |
| 477 | .IP "\fBPerlIO_findFILE(f)\fR" 4 |
| 478 | .IX Item "PerlIO_findFILE(f)" |
| 479 | Returns a native \s-1FILE\s0 * used by a stdio layer. If there is none, it |
| 480 | will create one with PerlIO_exportFILE. In either case the \s-1FILE\s0 * |
| 481 | should be considered as belonging to PerlIO subsystem and should |
| 482 | only be closed by calling \f(CW\*(C`PerlIO_close()\*(C'\fR. |
| 483 | .ie n .Sh """Fast gets"" Functions" |
| 484 | .el .Sh "``Fast gets'' Functions" |
| 485 | .IX Subsection "Fast gets Functions" |
| 486 | In addition to standard-like \s-1API\s0 defined so far above there is an |
| 487 | \&\*(L"implementation\*(R" interface which allows perl to get at internals of |
| 488 | PerlIO. The following calls correspond to the various FILE_xxx macros |
| 489 | determined by Configure \- or their equivalent in other |
| 490 | implementations. This section is really of interest to only those |
| 491 | concerned with detailed perl-core behaviour, implementing a PerlIO |
| 492 | mapping or writing code which can make use of the \*(L"read ahead\*(R" that |
| 493 | has been done by the \s-1IO\s0 system in the same way perl does. Note that |
| 494 | any code that uses these interfaces must be prepared to do things the |
| 495 | traditional way if a handle does not support them. |
| 496 | .IP "\fBPerlIO_fast_gets(f)\fR" 4 |
| 497 | .IX Item "PerlIO_fast_gets(f)" |
| 498 | Returns true if implementation has all the interfaces required to |
| 499 | allow perl's \f(CW\*(C`sv_gets\*(C'\fR to \*(L"bypass\*(R" normal \s-1IO\s0 mechanism. |
| 500 | This can vary from handle to handle. |
| 501 | .Sp |
| 502 | .Vb 3 |
| 503 | \& PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \e |
| 504 | \& PerlIO_canset_cnt(f) && \e |
| 505 | \& `Can set pointer into buffer' |
| 506 | .Ve |
| 507 | .IP "\fBPerlIO_has_cntptr(f)\fR" 4 |
| 508 | .IX Item "PerlIO_has_cntptr(f)" |
| 509 | Implementation can return pointer to current position in the \*(L"buffer\*(R" |
| 510 | and a count of bytes available in the buffer. Do not use this \- use |
| 511 | PerlIO_fast_gets. |
| 512 | .IP "\fBPerlIO_get_cnt(f)\fR" 4 |
| 513 | .IX Item "PerlIO_get_cnt(f)" |
| 514 | Return count of readable bytes in the buffer. Zero or negative return |
| 515 | means no more bytes available. |
| 516 | .IP "\fBPerlIO_get_ptr(f)\fR" 4 |
| 517 | .IX Item "PerlIO_get_ptr(f)" |
| 518 | Return pointer to next readable byte in buffer, accessing via the |
| 519 | pointer (dereferencing) is only safe if \fIPerlIO_get_cnt()\fR has returned |
| 520 | a positive value. Only positive offsets up to value returned by |
| 521 | \&\fIPerlIO_get_cnt()\fR are allowed. |
| 522 | .IP "\fBPerlIO_set_ptrcnt(f,p,c)\fR" 4 |
| 523 | .IX Item "PerlIO_set_ptrcnt(f,p,c)" |
| 524 | Set pointer into buffer, and a count of bytes still in the |
| 525 | buffer. Should be used only to set pointer to within range implied by |
| 526 | previous calls to \f(CW\*(C`PerlIO_get_ptr\*(C'\fR and \f(CW\*(C`PerlIO_get_cnt\*(C'\fR. The two |
| 527 | values \fImust\fR be consistent with each other (implementation may only |
| 528 | use one or the other or may require both). |
| 529 | .IP "\fBPerlIO_canset_cnt(f)\fR" 4 |
| 530 | .IX Item "PerlIO_canset_cnt(f)" |
| 531 | Implementation can adjust its idea of number of bytes in the buffer. |
| 532 | Do not use this \- use PerlIO_fast_gets. |
| 533 | .IP "\fBPerlIO_set_cnt(f,c)\fR" 4 |
| 534 | .IX Item "PerlIO_set_cnt(f,c)" |
| 535 | Obscure \- set count of bytes in the buffer. Deprecated. Only usable |
| 536 | if \fIPerlIO_canset_cnt()\fR returns true. Currently used in only doio.c to |
| 537 | force count less than \-1 to \-1. Perhaps should be PerlIO_set_empty or |
| 538 | similar. This call may actually do nothing if \*(L"count\*(R" is deduced from |
| 539 | pointer and a \*(L"limit\*(R". Do not use this \- use \fIPerlIO_set_ptrcnt()\fR. |
| 540 | .IP "\fBPerlIO_has_base(f)\fR" 4 |
| 541 | .IX Item "PerlIO_has_base(f)" |
| 542 | Returns true if implementation has a buffer, and can return pointer |
| 543 | to whole buffer and its size. Used by perl for \fB\-T\fR / \fB\-B\fR tests. |
| 544 | Other uses would be very obscure... |
| 545 | .IP "\fBPerlIO_get_base(f)\fR" 4 |
| 546 | .IX Item "PerlIO_get_base(f)" |
| 547 | Return \fIstart\fR of buffer. Access only positive offsets in the buffer |
| 548 | up to the value returned by \fIPerlIO_get_bufsiz()\fR. |
| 549 | .IP "\fBPerlIO_get_bufsiz(f)\fR" 4 |
| 550 | .IX Item "PerlIO_get_bufsiz(f)" |
| 551 | Return the \fItotal number of bytes\fR in the buffer, this is neither the |
| 552 | number that can be read, nor the amount of memory allocated to the |
| 553 | buffer. Rather it is what the operating system and/or implementation |
| 554 | happened to \f(CW\*(C`read()\*(C'\fR (or whatever) last time \s-1IO\s0 was requested. |
| 555 | .Sh "Other Functions" |
| 556 | .IX Subsection "Other Functions" |
| 557 | .IP "PerlIO_apply_layers(f,mode,layers)" 4 |
| 558 | .IX Item "PerlIO_apply_layers(f,mode,layers)" |
| 559 | The new interface to the \s-1USE_PERLIO\s0 implementation. The layers \*(L":crlf\*(R" |
| 560 | and \*(L":raw\*(R" are only ones allowed for other implementations and those |
| 561 | are silently ignored. (As of perl5.8 \*(L":raw\*(R" is deprecated.) |
| 562 | Use \fIPerlIO_binmode()\fR below for the portable case. |
| 563 | .IP "PerlIO_binmode(f,ptype,imode,layers)" 4 |
| 564 | .IX Item "PerlIO_binmode(f,ptype,imode,layers)" |
| 565 | The hook used by perl's \f(CW\*(C`binmode\*(C'\fR operator. |
| 566 | \&\fBptype\fR is perl's character for the kind of \s-1IO:\s0 |
| 567 | .RS 4 |
| 568 | .IP "'<' read" 8 |
| 569 | .IX Item "'<' read" |
| 570 | .PD 0 |
| 571 | .IP "'>' write" 8 |
| 572 | .IX Item "'>' write" |
| 573 | .IP "'+' read/write" 8 |
| 574 | .IX Item "'+' read/write" |
| 575 | .RE |
| 576 | .RS 4 |
| 577 | .PD |
| 578 | .Sp |
| 579 | \&\fBimode\fR is \f(CW\*(C`O_BINARY\*(C'\fR or \f(CW\*(C`O_TEXT\*(C'\fR. |
| 580 | .Sp |
| 581 | \&\fBlayers\fR is a string of layers to apply, only \*(L":crlf\*(R" makes sense in the non \s-1USE_PERLIO\s0 |
| 582 | case. (As of perl5.8 \*(L":raw\*(R" is deprecated in favour of passing \s-1NULL\s0.) |
| 583 | .Sp |
| 584 | Portable cases are: |
| 585 | .Sp |
| 586 | .Vb 3 |
| 587 | \& PerlIO_binmode(f,ptype,O_BINARY,Nullch); |
| 588 | \&and |
| 589 | \& PerlIO_binmode(f,ptype,O_TEXT,":crlf"); |
| 590 | .Ve |
| 591 | .Sp |
| 592 | On Unix these calls probably have no effect whatsoever. Elsewhere |
| 593 | they alter \*(L"\en\*(R" to \s-1CR\s0,LF translation and possibly cause a special text |
| 594 | \&\*(L"end of file\*(R" indicator to be written or honoured on read. The effect |
| 595 | of making the call after doing any \s-1IO\s0 to the handle depends on the |
| 596 | implementation. (It may be ignored, affect any data which is already |
| 597 | buffered as well, or only apply to subsequent data.) |
| 598 | .RE |
| 599 | .IP "PerlIO_debug(fmt,...)" 4 |
| 600 | .IX Item "PerlIO_debug(fmt,...)" |
| 601 | PerlIO_debug is a \fIprintf()\fR\-like function which can be used for |
| 602 | debugging. No return value. Its main use is inside PerlIO where using |
| 603 | real printf, \fIwarn()\fR etc. would recursively call PerlIO and be a |
| 604 | problem. |
| 605 | .Sp |
| 606 | PerlIO_debug writes to the file named by \f(CW$ENV\fR{'\s-1PERLIO_DEBUG\s0'} typical |
| 607 | use might be |
| 608 | .Sp |
| 609 | .Vb 2 |
| 610 | \& Bourne shells (sh, ksh, bash, zsh, ash, ...): |
| 611 | \& PERLIO_DEBUG=/dev/tty ./perl somescript some args |
| 612 | .Ve |
| 613 | .Sp |
| 614 | .Vb 3 |
| 615 | \& Csh/Tcsh: |
| 616 | \& setenv PERLIO_DEBUG /dev/tty |
| 617 | \& ./perl somescript some args |
| 618 | .Ve |
| 619 | .Sp |
| 620 | .Vb 2 |
| 621 | \& If you have the "env" utility: |
| 622 | \& env PERLIO_DEBUG=/dev/tty ./perl somescript some args |
| 623 | .Ve |
| 624 | .Sp |
| 625 | .Vb 3 |
| 626 | \& Win32: |
| 627 | \& set PERLIO_DEBUG=CON |
| 628 | \& perl somescript some args |
| 629 | .Ve |
| 630 | .Sp |
| 631 | If \f(CW$ENV\fR{'\s-1PERLIO_DEBUG\s0'} is not set \fIPerlIO_debug()\fR is a no\-op. |