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