| 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 "PERLIOL 1" |
| 58 |
.TH PERLIOL 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 |
perliol \- C API for Perl's implementation of IO in Layers. |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 2 |
| 68 |
\& /* Defining a layer ... */ |
| 69 |
\& #include <perliol.h> |
| 70 |
.Ve |
| 71 |
.SH DESCRIPTION |
| 72 |
.IX Header "DESCRIPTION" |
| 73 |
This document describes the behavior and implementation of the PerlIO |
| 74 |
abstraction described in perlapio when \f(CW\*(C`USE_PERLIO\*(C'\fR is defined. |
| 75 |
.SS "History and Background" |
| 76 |
.IX Subsection "History and Background" |
| 77 |
The PerlIO abstraction was introduced in perl5.003_02 but languished as |
| 78 |
just an abstraction until perl5.7.0. However during that time a number |
| 79 |
of perl extensions switched to using it, so the API is mostly fixed to |
| 80 |
maintain (source) compatibility. |
| 81 |
.PP |
| 82 |
The aim of the implementation is to provide the PerlIO API in a flexible |
| 83 |
and platform neutral manner. It is also a trial of an "Object Oriented |
| 84 |
C, with vtables" approach which may be applied to Raku. |
| 85 |
.SS "Basic Structure" |
| 86 |
.IX Subsection "Basic Structure" |
| 87 |
PerlIO is a stack of layers. |
| 88 |
.PP |
| 89 |
The low levels of the stack work with the low-level operating system |
| 90 |
calls (file descriptors in C) getting bytes in and out, the higher |
| 91 |
layers of the stack buffer, filter, and otherwise manipulate the I/O, |
| 92 |
and return characters (or bytes) to Perl. Terms \fIabove\fR and \fIbelow\fR |
| 93 |
are used to refer to the relative positioning of the stack layers. |
| 94 |
.PP |
| 95 |
A layer contains a "vtable", the table of I/O operations (at C level |
| 96 |
a table of function pointers), and status flags. The functions in the |
| 97 |
vtable implement operations like "open", "read", and "write". |
| 98 |
.PP |
| 99 |
When I/O, for example "read", is requested, the request goes from Perl |
| 100 |
first down the stack using "read" functions of each layer, then at the |
| 101 |
bottom the input is requested from the operating system services, then |
| 102 |
the result is returned up the stack, finally being interpreted as Perl |
| 103 |
data. |
| 104 |
.PP |
| 105 |
The requests do not necessarily go always all the way down to the |
| 106 |
operating system: that's where PerlIO buffering comes into play. |
| 107 |
.PP |
| 108 |
When you do an \fBopen()\fR and specify extra PerlIO layers to be deployed, |
| 109 |
the layers you specify are "pushed" on top of the already existing |
| 110 |
default stack. One way to see it is that "operating system is |
| 111 |
on the left" and "Perl is on the right". |
| 112 |
.PP |
| 113 |
What exact layers are in this default stack depends on a lot of |
| 114 |
things: your operating system, Perl version, Perl compile time |
| 115 |
configuration, and Perl runtime configuration. See PerlIO, |
| 116 |
"PERLIO" in perlrun, and open for more information. |
| 117 |
.PP |
| 118 |
\&\fBbinmode()\fR operates similarly to \fBopen()\fR: by default the specified |
| 119 |
layers are pushed on top of the existing stack. |
| 120 |
.PP |
| 121 |
However, note that even as the specified layers are "pushed on top" |
| 122 |
for \fBopen()\fR and \fBbinmode()\fR, this doesn't mean that the effects are |
| 123 |
limited to the "top": PerlIO layers can be very 'active' and inspect |
| 124 |
and affect layers also deeper in the stack. As an example there |
| 125 |
is a layer called "raw" which repeatedly "pops" layers until |
| 126 |
it reaches the first layer that has declared itself capable of |
| 127 |
handling binary data. The "pushed" layers are processed in left-to-right |
| 128 |
order. |
| 129 |
.PP |
| 130 |
\&\fBsysopen()\fR operates (unsurprisingly) at a lower level in the stack than |
| 131 |
\&\fBopen()\fR. For example in Unix or Unix-like systems \fBsysopen()\fR operates |
| 132 |
directly at the level of file descriptors: in the terms of PerlIO |
| 133 |
layers, it uses only the "unix" layer, which is a rather thin wrapper |
| 134 |
on top of the Unix file descriptors. |
| 135 |
.SS "Layers vs Disciplines" |
| 136 |
.IX Subsection "Layers vs Disciplines" |
| 137 |
Initial discussion of the ability to modify IO streams behaviour used |
| 138 |
the term "discipline" for the entities which were added. This came (I |
| 139 |
believe) from the use of the term in "sfio", which in turn borrowed it |
| 140 |
from "line disciplines" on Unix terminals. However, this document (and |
| 141 |
the C code) uses the term "layer". |
| 142 |
.PP |
| 143 |
This is, I hope, a natural term given the implementation, and should |
| 144 |
avoid connotations that are inherent in earlier uses of "discipline" |
| 145 |
for things which are rather different. |
| 146 |
.SS "Data Structures" |
| 147 |
.IX Subsection "Data Structures" |
| 148 |
The basic data structure is a PerlIOl: |
| 149 |
.PP |
| 150 |
.Vb 3 |
| 151 |
\& typedef struct _PerlIO PerlIOl; |
| 152 |
\& typedef struct _PerlIO_funcs PerlIO_funcs; |
| 153 |
\& typedef PerlIOl *PerlIO; |
| 154 |
\& |
| 155 |
\& struct _PerlIO |
| 156 |
\& { |
| 157 |
\& PerlIOl * next; /* Lower layer */ |
| 158 |
\& PerlIO_funcs * tab; /* Functions for this layer */ |
| 159 |
\& U32 flags; /* Various flags for state */ |
| 160 |
\& }; |
| 161 |
.Ve |
| 162 |
.PP |
| 163 |
A \f(CW\*(C`PerlIOl *\*(C'\fR is a pointer to the struct, and the \fIapplication\fR |
| 164 |
level \f(CW\*(C`PerlIO *\*(C'\fR is a pointer to a \f(CW\*(C`PerlIOl *\*(C'\fR \- i.e. a pointer |
| 165 |
to a pointer to the struct. This allows the application level \f(CW\*(C`PerlIO *\*(C'\fR |
| 166 |
to remain constant while the actual \f(CW\*(C`PerlIOl *\*(C'\fR underneath |
| 167 |
changes. (Compare perl's \f(CW\*(C`SV *\*(C'\fR which remains constant while its |
| 168 |
\&\f(CW\*(C`sv_any\*(C'\fR field changes as the scalar's type changes.) An IO stream is |
| 169 |
then in general represented as a pointer to this linked-list of |
| 170 |
"layers". |
| 171 |
.PP |
| 172 |
It should be noted that because of the double indirection in a \f(CW\*(C`PerlIO *\*(C'\fR, |
| 173 |
a \f(CW\*(C`&(perlio\->next)\*(C'\fR "is" a \f(CW\*(C`PerlIO *\*(C'\fR, and so to some degree |
| 174 |
at least one layer can use the "standard" API on the next layer down. |
| 175 |
.PP |
| 176 |
A "layer" is composed of two parts: |
| 177 |
.IP 1. 4 |
| 178 |
The functions and attributes of the "layer class". |
| 179 |
.IP 2. 4 |
| 180 |
The per-instance data for a particular handle. |
| 181 |
.SS "Functions and Attributes" |
| 182 |
.IX Subsection "Functions and Attributes" |
| 183 |
The functions and attributes are accessed via the "tab" (for table) |
| 184 |
member of \f(CW\*(C`PerlIOl\*(C'\fR. The functions (methods of the layer "class") are |
| 185 |
fixed, and are defined by the \f(CW\*(C`PerlIO_funcs\*(C'\fR type. They are broadly the |
| 186 |
same as the public \f(CW\*(C`PerlIO_xxxxx\*(C'\fR functions: |
| 187 |
.PP |
| 188 |
.Vb 10 |
| 189 |
\& struct _PerlIO_funcs |
| 190 |
\& { |
| 191 |
\& Size_t fsize; |
| 192 |
\& char * name; |
| 193 |
\& Size_t size; |
| 194 |
\& IV kind; |
| 195 |
\& IV (*Pushed)(pTHX_ PerlIO *f, |
| 196 |
\& const char *mode, |
| 197 |
\& SV *arg, |
| 198 |
\& PerlIO_funcs *tab); |
| 199 |
\& IV (*Popped)(pTHX_ PerlIO *f); |
| 200 |
\& PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, |
| 201 |
\& PerlIO_list_t *layers, IV n, |
| 202 |
\& const char *mode, |
| 203 |
\& int fd, int imode, int perm, |
| 204 |
\& PerlIO *old, |
| 205 |
\& int narg, SV **args); |
| 206 |
\& IV (*Binmode)(pTHX_ PerlIO *f); |
| 207 |
\& SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags) |
| 208 |
\& IV (*Fileno)(pTHX_ PerlIO *f); |
| 209 |
\& PerlIO * (*Dup)(pTHX_ PerlIO *f, |
| 210 |
\& PerlIO *o, |
| 211 |
\& CLONE_PARAMS *param, |
| 212 |
\& int flags) |
| 213 |
\& /* Unix\-like functions \- cf sfio line disciplines */ |
| 214 |
\& SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); |
| 215 |
\& SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); |
| 216 |
\& SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); |
| 217 |
\& IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); |
| 218 |
\& Off_t (*Tell)(pTHX_ PerlIO *f); |
| 219 |
\& IV (*Close)(pTHX_ PerlIO *f); |
| 220 |
\& /* Stdio\-like buffered IO functions */ |
| 221 |
\& IV (*Flush)(pTHX_ PerlIO *f); |
| 222 |
\& IV (*Fill)(pTHX_ PerlIO *f); |
| 223 |
\& IV (*Eof)(pTHX_ PerlIO *f); |
| 224 |
\& IV (*Error)(pTHX_ PerlIO *f); |
| 225 |
\& void (*Clearerr)(pTHX_ PerlIO *f); |
| 226 |
\& void (*Setlinebuf)(pTHX_ PerlIO *f); |
| 227 |
\& /* Perl\*(Aqs snooping functions */ |
| 228 |
\& STDCHAR * (*Get_base)(pTHX_ PerlIO *f); |
| 229 |
\& Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); |
| 230 |
\& STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); |
| 231 |
\& SSize_t (*Get_cnt)(pTHX_ PerlIO *f); |
| 232 |
\& void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt); |
| 233 |
\& }; |
| 234 |
.Ve |
| 235 |
.PP |
| 236 |
The first few members of the struct give a function table size for |
| 237 |
compatibility check "name" for the layer, the size to \f(CW\*(C`malloc\*(C'\fR for the per-instance data, |
| 238 |
and some flags which are attributes of the class as whole (such as whether it is a buffering |
| 239 |
layer), then follow the functions which fall into four basic groups: |
| 240 |
.IP 1. 4 |
| 241 |
Opening and setup functions |
| 242 |
.IP 2. 4 |
| 243 |
Basic IO operations |
| 244 |
.IP 3. 4 |
| 245 |
Stdio class buffering options. |
| 246 |
.IP 4. 4 |
| 247 |
Functions to support Perl's traditional "fast" access to the buffer. |
| 248 |
.PP |
| 249 |
A layer does not have to implement all the functions, but the whole |
| 250 |
table has to be present. Unimplemented slots can be NULL (which will |
| 251 |
result in an error when called) or can be filled in with stubs to |
| 252 |
"inherit" behaviour from a "base class". This "inheritance" is fixed |
| 253 |
for all instances of the layer, but as the layer chooses which stubs |
| 254 |
to populate the table, limited "multiple inheritance" is possible. |
| 255 |
.SS "Per-instance Data" |
| 256 |
.IX Subsection "Per-instance Data" |
| 257 |
The per-instance data are held in memory beyond the basic PerlIOl |
| 258 |
struct, by making a PerlIOl the first member of the layer's struct |
| 259 |
thus: |
| 260 |
.PP |
| 261 |
.Vb 10 |
| 262 |
\& typedef struct |
| 263 |
\& { |
| 264 |
\& struct _PerlIO base; /* Base "class" info */ |
| 265 |
\& STDCHAR * buf; /* Start of buffer */ |
| 266 |
\& STDCHAR * end; /* End of valid part of buffer */ |
| 267 |
\& STDCHAR * ptr; /* Current position in buffer */ |
| 268 |
\& Off_t posn; /* Offset of buf into the file */ |
| 269 |
\& Size_t bufsiz; /* Real size of buffer */ |
| 270 |
\& IV oneword; /* Emergency buffer */ |
| 271 |
\& } PerlIOBuf; |
| 272 |
.Ve |
| 273 |
.PP |
| 274 |
In this way (as for perl's scalars) a pointer to a PerlIOBuf can be |
| 275 |
treated as a pointer to a PerlIOl. |
| 276 |
.SS "Layers in action" |
| 277 |
.IX Subsection "Layers in action" |
| 278 |
.Vb 8 |
| 279 |
\& table perlio unix |
| 280 |
\& | | |
| 281 |
\& +\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-+ |
| 282 |
\& PerlIO \->| |\-\-\->| next |\-\-\->| NULL | |
| 283 |
\& +\-\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-\-\-+ +\-\-\-\-\-\-\-\-+ |
| 284 |
\& | | | buffer | | fd | |
| 285 |
\& +\-\-\-\-\-\-\-\-\-\-\-+ | | +\-\-\-\-\-\-\-\-+ |
| 286 |
\& | | +\-\-\-\-\-\-\-\-\-\-+ |
| 287 |
.Ve |
| 288 |
.PP |
| 289 |
The above attempts to show how the layer scheme works in a simple case. |
| 290 |
The application's \f(CW\*(C`PerlIO *\*(C'\fR points to an entry in the table(s) |
| 291 |
representing open (allocated) handles. For example the first three slots |
| 292 |
in the table correspond to \f(CW\*(C`stdin\*(C'\fR,\f(CW\*(C`stdout\*(C'\fR and \f(CW\*(C`stderr\*(C'\fR. The table |
| 293 |
in turn points to the current "top" layer for the handle \- in this case |
| 294 |
an instance of the generic buffering layer "perlio". That layer in turn |
| 295 |
points to the next layer down \- in this case the low-level "unix" layer. |
| 296 |
.PP |
| 297 |
The above is roughly equivalent to a "stdio" buffered stream, but with |
| 298 |
much more flexibility: |
| 299 |
.IP \(bu 4 |
| 300 |
If Unix level \f(CW\*(C`read\*(C'\fR/\f(CW\*(C`write\*(C'\fR/\f(CW\*(C`lseek\*(C'\fR is not appropriate for (say) |
| 301 |
sockets then the "unix" layer can be replaced (at open time or even |
| 302 |
dynamically) with a "socket" layer. |
| 303 |
.IP \(bu 4 |
| 304 |
Different handles can have different buffering schemes. The "top" |
| 305 |
layer could be the "mmap" layer if reading disk files was quicker |
| 306 |
using \f(CW\*(C`mmap\*(C'\fR than \f(CW\*(C`read\*(C'\fR. An "unbuffered" stream can be implemented |
| 307 |
simply by not having a buffer layer. |
| 308 |
.IP \(bu 4 |
| 309 |
Extra layers can be inserted to process the data as it flows through. |
| 310 |
This was the driving need for including the scheme in perl 5.7.0+ \- we |
| 311 |
needed a mechanism to allow data to be translated between perl's |
| 312 |
internal encoding (conceptually at least Unicode as UTF\-8), and the |
| 313 |
"native" format used by the system. This is provided by the |
| 314 |
":encoding(xxxx)" layer which typically sits above the buffering layer. |
| 315 |
.IP \(bu 4 |
| 316 |
A layer can be added that does "\en" to CRLF translation. This layer |
| 317 |
can be used on any platform, not just those that normally do such |
| 318 |
things. |
| 319 |
.SS "Per-instance flag bits" |
| 320 |
.IX Subsection "Per-instance flag bits" |
| 321 |
The generic flag bits are a hybrid of \f(CW\*(C`O_XXXXX\*(C'\fR style flags deduced |
| 322 |
from the mode string passed to \f(CWPerlIO_open()\fR, and state bits for |
| 323 |
typical buffer layers. |
| 324 |
.IP PERLIO_F_EOF 4 |
| 325 |
.IX Item "PERLIO_F_EOF" |
| 326 |
End of file. |
| 327 |
.IP PERLIO_F_CANWRITE 4 |
| 328 |
.IX Item "PERLIO_F_CANWRITE" |
| 329 |
Writes are permitted, i.e. opened as "w" or "r+" or "a", etc. |
| 330 |
.IP PERLIO_F_CANREAD 4 |
| 331 |
.IX Item "PERLIO_F_CANREAD" |
| 332 |
Reads are permitted i.e. opened "r" or "w+" (or even "a+" \- ick). |
| 333 |
.IP PERLIO_F_ERROR 4 |
| 334 |
.IX Item "PERLIO_F_ERROR" |
| 335 |
An error has occurred (for \f(CWPerlIO_error()\fR). |
| 336 |
.IP PERLIO_F_TRUNCATE 4 |
| 337 |
.IX Item "PERLIO_F_TRUNCATE" |
| 338 |
Truncate file suggested by open mode. |
| 339 |
.IP PERLIO_F_APPEND 4 |
| 340 |
.IX Item "PERLIO_F_APPEND" |
| 341 |
All writes should be appends. |
| 342 |
.IP PERLIO_F_CRLF 4 |
| 343 |
.IX Item "PERLIO_F_CRLF" |
| 344 |
Layer is performing Win32\-like "\en" mapped to CR,LF for output and CR,LF |
| 345 |
mapped to "\en" for input. Normally the provided "crlf" layer is the only |
| 346 |
layer that need bother about this. \f(CWPerlIO_binmode()\fR will mess with this |
| 347 |
flag rather than add/remove layers if the \f(CW\*(C`PERLIO_K_CANCRLF\*(C'\fR bit is set |
| 348 |
for the layers class. |
| 349 |
.IP PERLIO_F_UTF8 4 |
| 350 |
.IX Item "PERLIO_F_UTF8" |
| 351 |
Data written to this layer should be UTF\-8 encoded; data provided |
| 352 |
by this layer should be considered UTF\-8 encoded. Can be set on any layer |
| 353 |
by ":utf8" dummy layer. Also set on ":encoding" layer. |
| 354 |
.IP PERLIO_F_UNBUF 4 |
| 355 |
.IX Item "PERLIO_F_UNBUF" |
| 356 |
Layer is unbuffered \- i.e. write to next layer down should occur for |
| 357 |
each write to this layer. |
| 358 |
.IP PERLIO_F_WRBUF 4 |
| 359 |
.IX Item "PERLIO_F_WRBUF" |
| 360 |
The buffer for this layer currently holds data written to it but not sent |
| 361 |
to next layer. |
| 362 |
.IP PERLIO_F_RDBUF 4 |
| 363 |
.IX Item "PERLIO_F_RDBUF" |
| 364 |
The buffer for this layer currently holds unconsumed data read from |
| 365 |
layer below. |
| 366 |
.IP PERLIO_F_LINEBUF 4 |
| 367 |
.IX Item "PERLIO_F_LINEBUF" |
| 368 |
Layer is line buffered. Write data should be passed to next layer down |
| 369 |
whenever a "\en" is seen. Any data beyond the "\en" should then be |
| 370 |
processed. |
| 371 |
.IP PERLIO_F_TEMP 4 |
| 372 |
.IX Item "PERLIO_F_TEMP" |
| 373 |
File has been \f(CWunlink()\fRed, or should be deleted on \f(CWclose()\fR. |
| 374 |
.IP PERLIO_F_OPEN 4 |
| 375 |
.IX Item "PERLIO_F_OPEN" |
| 376 |
Handle is open. |
| 377 |
.IP PERLIO_F_FASTGETS 4 |
| 378 |
.IX Item "PERLIO_F_FASTGETS" |
| 379 |
This instance of this layer supports the "fast \f(CW\*(C`gets\*(C'\fR" interface. |
| 380 |
Normally set based on \f(CW\*(C`PERLIO_K_FASTGETS\*(C'\fR for the class and by the |
| 381 |
existence of the function(s) in the table. However a class that |
| 382 |
normally provides that interface may need to avoid it on a |
| 383 |
particular instance. The "pending" layer needs to do this when |
| 384 |
it is pushed above a layer which does not support the interface. |
| 385 |
(Perl's \f(CWsv_gets()\fR does not expect the streams fast \f(CW\*(C`gets\*(C'\fR behaviour |
| 386 |
to change during one "get".) |
| 387 |
.SS "Methods in Detail" |
| 388 |
.IX Subsection "Methods in Detail" |
| 389 |
.IP fsize 4 |
| 390 |
.IX Item "fsize" |
| 391 |
.Vb 1 |
| 392 |
\& Size_t fsize; |
| 393 |
.Ve |
| 394 |
.Sp |
| 395 |
Size of the function table. This is compared against the value PerlIO |
| 396 |
code "knows" as a compatibility check. Future versions \fImay\fR be able |
| 397 |
to tolerate layers compiled against an old version of the headers. |
| 398 |
.IP name 4 |
| 399 |
.IX Item "name" |
| 400 |
.Vb 1 |
| 401 |
\& char * name; |
| 402 |
.Ve |
| 403 |
.Sp |
| 404 |
The name of the layer whose \fBopen()\fR method Perl should invoke on |
| 405 |
\&\fBopen()\fR. For example if the layer is called APR, you will call: |
| 406 |
.Sp |
| 407 |
.Vb 1 |
| 408 |
\& open $fh, ">:APR", ... |
| 409 |
.Ve |
| 410 |
.Sp |
| 411 |
and Perl knows that it has to invoke the \fBPerlIOAPR_open()\fR method |
| 412 |
implemented by the APR layer. |
| 413 |
.IP size 4 |
| 414 |
.IX Item "size" |
| 415 |
.Vb 1 |
| 416 |
\& Size_t size; |
| 417 |
.Ve |
| 418 |
.Sp |
| 419 |
The size of the per-instance data structure, e.g.: |
| 420 |
.Sp |
| 421 |
.Vb 1 |
| 422 |
\& sizeof(PerlIOAPR) |
| 423 |
.Ve |
| 424 |
.Sp |
| 425 |
If this field is zero then \f(CW\*(C`PerlIO_pushed\*(C'\fR does not malloc anything |
| 426 |
and assumes layer's Pushed function will do any required layer stack |
| 427 |
manipulation \- used to avoid malloc/free overhead for dummy layers. |
| 428 |
If the field is non-zero it must be at least the size of \f(CW\*(C`PerlIOl\*(C'\fR, |
| 429 |
\&\f(CW\*(C`PerlIO_pushed\*(C'\fR will allocate memory for the layer's data structures |
| 430 |
and link new layer onto the stream's stack. (If the layer's Pushed |
| 431 |
method returns an error indication the layer is popped again.) |
| 432 |
.IP kind 4 |
| 433 |
.IX Item "kind" |
| 434 |
.Vb 1 |
| 435 |
\& IV kind; |
| 436 |
.Ve |
| 437 |
.RS 4 |
| 438 |
.IP \(bu 4 |
| 439 |
PERLIO_K_BUFFERED |
| 440 |
.Sp |
| 441 |
The layer is buffered. |
| 442 |
.IP \(bu 4 |
| 443 |
PERLIO_K_RAW |
| 444 |
.Sp |
| 445 |
The layer is acceptable to have in a binmode(FH) stack \- i.e. it does not |
| 446 |
(or will configure itself not to) transform bytes passing through it. |
| 447 |
.IP \(bu 4 |
| 448 |
PERLIO_K_CANCRLF |
| 449 |
.Sp |
| 450 |
Layer can translate between "\en" and CRLF line ends. |
| 451 |
.IP \(bu 4 |
| 452 |
PERLIO_K_FASTGETS |
| 453 |
.Sp |
| 454 |
Layer allows buffer snooping. |
| 455 |
.IP \(bu 4 |
| 456 |
PERLIO_K_MULTIARG |
| 457 |
.Sp |
| 458 |
Used when the layer's \fBopen()\fR accepts more arguments than usual. The |
| 459 |
extra arguments should come not before the \f(CW\*(C`MODE\*(C'\fR argument. When this |
| 460 |
flag is used it's up to the layer to validate the args. |
| 461 |
.RE |
| 462 |
.RS 4 |
| 463 |
.RE |
| 464 |
.IP Pushed 4 |
| 465 |
.IX Item "Pushed" |
| 466 |
.Vb 1 |
| 467 |
\& IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg); |
| 468 |
.Ve |
| 469 |
.Sp |
| 470 |
The only absolutely mandatory method. Called when the layer is pushed |
| 471 |
onto the stack. The \f(CW\*(C`mode\*(C'\fR argument may be NULL if this occurs |
| 472 |
post-open. The \f(CW\*(C`arg\*(C'\fR will be non\-\f(CW\*(C`NULL\*(C'\fR if an argument string was |
| 473 |
passed. In most cases this should call \f(CWPerlIOBase_pushed()\fR to |
| 474 |
convert \f(CW\*(C`mode\*(C'\fR into the appropriate \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags in |
| 475 |
addition to any actions the layer itself takes. If a layer is not |
| 476 |
expecting an argument it need neither save the one passed to it, nor |
| 477 |
provide \f(CWGetarg()\fR (it could perhaps \f(CW\*(C`Perl_warn\*(C'\fR that the argument |
| 478 |
was un-expected). |
| 479 |
.Sp |
| 480 |
Returns 0 on success. On failure returns \-1 and should set errno. |
| 481 |
.IP Popped 4 |
| 482 |
.IX Item "Popped" |
| 483 |
.Vb 1 |
| 484 |
\& IV (*Popped)(pTHX_ PerlIO *f); |
| 485 |
.Ve |
| 486 |
.Sp |
| 487 |
Called when the layer is popped from the stack. A layer will normally |
| 488 |
be popped after \f(CWClose()\fR is called. But a layer can be popped |
| 489 |
without being closed if the program is dynamically managing layers on |
| 490 |
the stream. In such cases \f(CWPopped()\fR should free any resources |
| 491 |
(buffers, translation tables, ...) not held directly in the layer's |
| 492 |
struct. It should also \f(CWUnread()\fR any unconsumed data that has been |
| 493 |
read and buffered from the layer below back to that layer, so that it |
| 494 |
can be re-provided to what ever is now above. |
| 495 |
.Sp |
| 496 |
Returns 0 on success and failure. If \f(CWPopped()\fR returns \fItrue\fR then |
| 497 |
\&\fIperlio.c\fR assumes that either the layer has popped itself, or the |
| 498 |
layer is super special and needs to be retained for other reasons. |
| 499 |
In most cases it should return \fIfalse\fR. |
| 500 |
.IP Open 4 |
| 501 |
.IX Item "Open" |
| 502 |
.Vb 1 |
| 503 |
\& PerlIO * (*Open)(...); |
| 504 |
.Ve |
| 505 |
.Sp |
| 506 |
The \f(CWOpen()\fR method has lots of arguments because it combines the |
| 507 |
functions of perl's \f(CW\*(C`open\*(C'\fR, \f(CW\*(C`PerlIO_open\*(C'\fR, perl's \f(CW\*(C`sysopen\*(C'\fR, |
| 508 |
\&\f(CW\*(C`PerlIO_fdopen\*(C'\fR and \f(CW\*(C`PerlIO_reopen\*(C'\fR. The full prototype is as |
| 509 |
follows: |
| 510 |
.Sp |
| 511 |
.Vb 6 |
| 512 |
\& PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, |
| 513 |
\& PerlIO_list_t *layers, IV n, |
| 514 |
\& const char *mode, |
| 515 |
\& int fd, int imode, int perm, |
| 516 |
\& PerlIO *old, |
| 517 |
\& int narg, SV **args); |
| 518 |
.Ve |
| 519 |
.Sp |
| 520 |
Open should (perhaps indirectly) call \f(CWPerlIO_allocate()\fR to allocate |
| 521 |
a slot in the table and associate it with the layers information for |
| 522 |
the opened file, by calling \f(CW\*(C`PerlIO_push\*(C'\fR. The \fIlayers\fR is an |
| 523 |
array of all the layers destined for the \f(CW\*(C`PerlIO *\*(C'\fR, and any |
| 524 |
arguments passed to them, \fIn\fR is the index into that array of the |
| 525 |
layer being called. The macro \f(CW\*(C`PerlIOArg\*(C'\fR will return a (possibly |
| 526 |
\&\f(CW\*(C`NULL\*(C'\fR) SV * for the argument passed to the layer. |
| 527 |
.Sp |
| 528 |
Where a layer opens or takes ownership of a file descriptor, that layer is |
| 529 |
responsible for getting the file descriptor's close-on-exec flag into the |
| 530 |
correct state. The flag should be clear for a file descriptor numbered |
| 531 |
less than or equal to \f(CW\*(C`PL_maxsysfd\*(C'\fR, and set for any file descriptor |
| 532 |
numbered higher. For thread safety, when a layer opens a new file |
| 533 |
descriptor it should if possible open it with the close-on-exec flag |
| 534 |
initially set. |
| 535 |
.Sp |
| 536 |
The \fImode\fR string is an "\f(CWfopen()\fR\-like" string which would match |
| 537 |
the regular expression \f(CW\*(C`/^[I#]?[rwa]\e+?[bt]?$/\*(C'\fR. |
| 538 |
.Sp |
| 539 |
The \f(CW\*(AqI\*(Aq\fR prefix is used during creation of \f(CW\*(C`stdin\*(C'\fR..\f(CW\*(C`stderr\*(C'\fR via |
| 540 |
special \f(CW\*(C`PerlIO_fdopen\*(C'\fR calls; the \f(CW\*(Aq#\*(Aq\fR prefix means that this is |
| 541 |
\&\f(CW\*(C`sysopen\*(C'\fR and that \fIimode\fR and \fIperm\fR should be passed to |
| 542 |
\&\f(CW\*(C`PerlLIO_open3\*(C'\fR; \f(CW\*(Aqr\*(Aq\fR means \fBr\fRead, \f(CW\*(Aqw\*(Aq\fR means \fBw\fRrite and |
| 543 |
\&\f(CW\*(Aqa\*(Aq\fR means \fBa\fRppend. The \f(CW\*(Aq+\*(Aq\fR suffix means that both reading and |
| 544 |
writing/appending are permitted. The \f(CW\*(Aqb\*(Aq\fR suffix means file should |
| 545 |
be binary, and \f(CW\*(Aqt\*(Aq\fR means it is text. (Almost all layers should do |
| 546 |
the IO in binary mode, and ignore the b/t bits. The \f(CW\*(C`:crlf\*(C'\fR layer |
| 547 |
should be pushed to handle the distinction.) |
| 548 |
.Sp |
| 549 |
If \fIold\fR is not \f(CW\*(C`NULL\*(C'\fR then this is a \f(CW\*(C`PerlIO_reopen\*(C'\fR. Perl itself |
| 550 |
does not use this (yet?) and semantics are a little vague. |
| 551 |
.Sp |
| 552 |
If \fIfd\fR not negative then it is the numeric file descriptor \fIfd\fR, |
| 553 |
which will be open in a manner compatible with the supplied mode |
| 554 |
string, the call is thus equivalent to \f(CW\*(C`PerlIO_fdopen\*(C'\fR. In this case |
| 555 |
\&\fInargs\fR will be zero. |
| 556 |
The file descriptor may have the close-on-exec flag either set or clear; |
| 557 |
it is the responsibility of the layer that takes ownership of it to get |
| 558 |
the flag into the correct state. |
| 559 |
.Sp |
| 560 |
If \fInargs\fR is greater than zero then it gives the number of arguments |
| 561 |
passed to \f(CW\*(C`open\*(C'\fR, otherwise it will be 1 if for example |
| 562 |
\&\f(CW\*(C`PerlIO_open\*(C'\fR was called. In simple cases SvPV_nolen(*args) is the |
| 563 |
pathname to open. |
| 564 |
.Sp |
| 565 |
If a layer provides \f(CWOpen()\fR it should normally call the \f(CWOpen()\fR |
| 566 |
method of next layer down (if any) and then push itself on top if that |
| 567 |
succeeds. \f(CW\*(C`PerlIOBase_open\*(C'\fR is provided to do exactly that, so in |
| 568 |
most cases you don't have to write your own \f(CWOpen()\fR method. If this |
| 569 |
method is not defined, other layers may have difficulty pushing |
| 570 |
themselves on top of it during open. |
| 571 |
.Sp |
| 572 |
If \f(CW\*(C`PerlIO_push\*(C'\fR was performed and open has failed, it must |
| 573 |
\&\f(CW\*(C`PerlIO_pop\*(C'\fR itself, since if it's not, the layer won't be removed |
| 574 |
and may cause bad problems. |
| 575 |
.Sp |
| 576 |
Returns \f(CW\*(C`NULL\*(C'\fR on failure. |
| 577 |
.IP Binmode 4 |
| 578 |
.IX Item "Binmode" |
| 579 |
.Vb 1 |
| 580 |
\& IV (*Binmode)(pTHX_ PerlIO *f); |
| 581 |
.Ve |
| 582 |
.Sp |
| 583 |
Optional. Used when \f(CW\*(C`:raw\*(C'\fR layer is pushed (explicitly or as a result |
| 584 |
of binmode(FH)). If not present layer will be popped. If present |
| 585 |
should configure layer as binary (or pop itself) and return 0. |
| 586 |
If it returns \-1 for error \f(CW\*(C`binmode\*(C'\fR will fail with layer |
| 587 |
still on the stack. |
| 588 |
.IP Getarg 4 |
| 589 |
.IX Item "Getarg" |
| 590 |
.Vb 2 |
| 591 |
\& SV * (*Getarg)(pTHX_ PerlIO *f, |
| 592 |
\& CLONE_PARAMS *param, int flags); |
| 593 |
.Ve |
| 594 |
.Sp |
| 595 |
Optional. If present should return an SV * representing the string |
| 596 |
argument passed to the layer when it was |
| 597 |
pushed. e.g. ":encoding(ascii)" would return an SvPV with value |
| 598 |
"ascii". (\fIparam\fR and \fIflags\fR arguments can be ignored in most |
| 599 |
cases) |
| 600 |
.Sp |
| 601 |
\&\f(CW\*(C`Dup\*(C'\fR uses \f(CW\*(C`Getarg\*(C'\fR to retrieve the argument originally passed to |
| 602 |
\&\f(CW\*(C`Pushed\*(C'\fR, so you must implement this function if your layer has an |
| 603 |
extra argument to \f(CW\*(C`Pushed\*(C'\fR and will ever be \f(CW\*(C`Dup\*(C'\fRed. |
| 604 |
.IP Fileno 4 |
| 605 |
.IX Item "Fileno" |
| 606 |
.Vb 1 |
| 607 |
\& IV (*Fileno)(pTHX_ PerlIO *f); |
| 608 |
.Ve |
| 609 |
.Sp |
| 610 |
Returns the Unix/Posix numeric file descriptor for the handle. Normally |
| 611 |
\&\f(CWPerlIOBase_fileno()\fR (which just asks next layer down) will suffice |
| 612 |
for this. |
| 613 |
.Sp |
| 614 |
Returns \-1 on error, which is considered to include the case where the |
| 615 |
layer cannot provide such a file descriptor. |
| 616 |
.IP Dup 4 |
| 617 |
.IX Item "Dup" |
| 618 |
.Vb 2 |
| 619 |
\& PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, |
| 620 |
\& CLONE_PARAMS *param, int flags); |
| 621 |
.Ve |
| 622 |
.Sp |
| 623 |
XXX: Needs more docs. |
| 624 |
.Sp |
| 625 |
Used as part of the "clone" process when a thread is spawned (in which |
| 626 |
case param will be non-NULL) and when a stream is being duplicated via |
| 627 |
\&'&' in the \f(CW\*(C`open\*(C'\fR. |
| 628 |
.Sp |
| 629 |
Similar to \f(CW\*(C`Open\*(C'\fR, returns PerlIO* on success, \f(CW\*(C`NULL\*(C'\fR on failure. |
| 630 |
.IP Read 4 |
| 631 |
.IX Item "Read" |
| 632 |
.Vb 1 |
| 633 |
\& SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); |
| 634 |
.Ve |
| 635 |
.Sp |
| 636 |
Basic read operation. |
| 637 |
.Sp |
| 638 |
Typically will call \f(CW\*(C`Fill\*(C'\fR and manipulate pointers (possibly via the |
| 639 |
API). \f(CWPerlIOBuf_read()\fR may be suitable for derived classes which |
| 640 |
provide "fast gets" methods. |
| 641 |
.Sp |
| 642 |
Returns actual bytes read, or \-1 on an error. |
| 643 |
.IP Unread 4 |
| 644 |
.IX Item "Unread" |
| 645 |
.Vb 2 |
| 646 |
\& SSize_t (*Unread)(pTHX_ PerlIO *f, |
| 647 |
\& const void *vbuf, Size_t count); |
| 648 |
.Ve |
| 649 |
.Sp |
| 650 |
A superset of stdio's \f(CWungetc()\fR. Should arrange for future reads to |
| 651 |
see the bytes in \f(CW\*(C`vbuf\*(C'\fR. If there is no obviously better implementation |
| 652 |
then \f(CWPerlIOBase_unread()\fR provides the function by pushing a "fake" |
| 653 |
"pending" layer above the calling layer. |
| 654 |
.Sp |
| 655 |
Returns the number of unread chars. |
| 656 |
.IP Write 4 |
| 657 |
.IX Item "Write" |
| 658 |
.Vb 1 |
| 659 |
\& SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); |
| 660 |
.Ve |
| 661 |
.Sp |
| 662 |
Basic write operation. |
| 663 |
.Sp |
| 664 |
Returns bytes written or \-1 on an error. |
| 665 |
.IP Seek 4 |
| 666 |
.IX Item "Seek" |
| 667 |
.Vb 1 |
| 668 |
\& IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); |
| 669 |
.Ve |
| 670 |
.Sp |
| 671 |
Position the file pointer. Should normally call its own \f(CW\*(C`Flush\*(C'\fR |
| 672 |
method and then the \f(CW\*(C`Seek\*(C'\fR method of next layer down. |
| 673 |
.Sp |
| 674 |
Returns 0 on success, \-1 on failure. |
| 675 |
.IP Tell 4 |
| 676 |
.IX Item "Tell" |
| 677 |
.Vb 1 |
| 678 |
\& Off_t (*Tell)(pTHX_ PerlIO *f); |
| 679 |
.Ve |
| 680 |
.Sp |
| 681 |
Return the file pointer. May be based on layers cached concept of |
| 682 |
position to avoid overhead. |
| 683 |
.Sp |
| 684 |
Returns \-1 on failure to get the file pointer. |
| 685 |
.IP Close 4 |
| 686 |
.IX Item "Close" |
| 687 |
.Vb 1 |
| 688 |
\& IV (*Close)(pTHX_ PerlIO *f); |
| 689 |
.Ve |
| 690 |
.Sp |
| 691 |
Close the stream. Should normally call \f(CWPerlIOBase_close()\fR to flush |
| 692 |
itself and close layers below, and then deallocate any data structures |
| 693 |
(buffers, translation tables, ...) not held directly in the data |
| 694 |
structure. |
| 695 |
.Sp |
| 696 |
Returns 0 on success, \-1 on failure. |
| 697 |
.IP Flush 4 |
| 698 |
.IX Item "Flush" |
| 699 |
.Vb 1 |
| 700 |
\& IV (*Flush)(pTHX_ PerlIO *f); |
| 701 |
.Ve |
| 702 |
.Sp |
| 703 |
Should make stream's state consistent with layers below. That is, any |
| 704 |
buffered write data should be written, and file position of lower layers |
| 705 |
adjusted for data read from below but not actually consumed. |
| 706 |
(Should perhaps \f(CWUnread()\fR such data to the lower layer.) |
| 707 |
.Sp |
| 708 |
Returns 0 on success, \-1 on failure. |
| 709 |
.IP Fill 4 |
| 710 |
.IX Item "Fill" |
| 711 |
.Vb 1 |
| 712 |
\& IV (*Fill)(pTHX_ PerlIO *f); |
| 713 |
.Ve |
| 714 |
.Sp |
| 715 |
The buffer for this layer should be filled (for read) from layer |
| 716 |
below. When you "subclass" PerlIOBuf layer, you want to use its |
| 717 |
\&\fI_read\fR method and to supply your own fill method, which fills the |
| 718 |
PerlIOBuf's buffer. |
| 719 |
.Sp |
| 720 |
Returns 0 on success, \-1 on failure. |
| 721 |
.IP Eof 4 |
| 722 |
.IX Item "Eof" |
| 723 |
.Vb 1 |
| 724 |
\& IV (*Eof)(pTHX_ PerlIO *f); |
| 725 |
.Ve |
| 726 |
.Sp |
| 727 |
Return end-of-file indicator. \f(CWPerlIOBase_eof()\fR is normally sufficient. |
| 728 |
.Sp |
| 729 |
Returns 0 on end-of-file, 1 if not end-of-file, \-1 on error. |
| 730 |
.IP Error 4 |
| 731 |
.IX Item "Error" |
| 732 |
.Vb 1 |
| 733 |
\& IV (*Error)(pTHX_ PerlIO *f); |
| 734 |
.Ve |
| 735 |
.Sp |
| 736 |
Return error indicator. \f(CWPerlIOBase_error()\fR is normally sufficient. |
| 737 |
.Sp |
| 738 |
Returns 1 if there is an error (usually when \f(CW\*(C`PERLIO_F_ERROR\*(C'\fR is set), |
| 739 |
0 otherwise. |
| 740 |
.IP Clearerr 4 |
| 741 |
.IX Item "Clearerr" |
| 742 |
.Vb 1 |
| 743 |
\& void (*Clearerr)(pTHX_ PerlIO *f); |
| 744 |
.Ve |
| 745 |
.Sp |
| 746 |
Clear end-of-file and error indicators. Should call \f(CWPerlIOBase_clearerr()\fR |
| 747 |
to set the \f(CW\*(C`PERLIO_F_XXXXX\*(C'\fR flags, which may suffice. |
| 748 |
.IP Setlinebuf 4 |
| 749 |
.IX Item "Setlinebuf" |
| 750 |
.Vb 1 |
| 751 |
\& void (*Setlinebuf)(pTHX_ PerlIO *f); |
| 752 |
.Ve |
| 753 |
.Sp |
| 754 |
Mark the stream as line buffered. \f(CWPerlIOBase_setlinebuf()\fR sets the |
| 755 |
PERLIO_F_LINEBUF flag and is normally sufficient. |
| 756 |
.IP Get_base 4 |
| 757 |
.IX Item "Get_base" |
| 758 |
.Vb 1 |
| 759 |
\& STDCHAR * (*Get_base)(pTHX_ PerlIO *f); |
| 760 |
.Ve |
| 761 |
.Sp |
| 762 |
Allocate (if not already done so) the read buffer for this layer and |
| 763 |
return pointer to it. Return NULL on failure. |
| 764 |
.IP Get_bufsiz 4 |
| 765 |
.IX Item "Get_bufsiz" |
| 766 |
.Vb 1 |
| 767 |
\& Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); |
| 768 |
.Ve |
| 769 |
.Sp |
| 770 |
Return the number of bytes that last \f(CWFill()\fR put in the buffer. |
| 771 |
.IP Get_ptr 4 |
| 772 |
.IX Item "Get_ptr" |
| 773 |
.Vb 1 |
| 774 |
\& STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); |
| 775 |
.Ve |
| 776 |
.Sp |
| 777 |
Return the current read pointer relative to this layer's buffer. |
| 778 |
.IP Get_cnt 4 |
| 779 |
.IX Item "Get_cnt" |
| 780 |
.Vb 1 |
| 781 |
\& SSize_t (*Get_cnt)(pTHX_ PerlIO *f); |
| 782 |
.Ve |
| 783 |
.Sp |
| 784 |
Return the number of bytes left to be read in the current buffer. |
| 785 |
.IP Set_ptrcnt 4 |
| 786 |
.IX Item "Set_ptrcnt" |
| 787 |
.Vb 2 |
| 788 |
\& void (*Set_ptrcnt)(pTHX_ PerlIO *f, |
| 789 |
\& STDCHAR *ptr, SSize_t cnt); |
| 790 |
.Ve |
| 791 |
.Sp |
| 792 |
Adjust the read pointer and count of bytes to match \f(CW\*(C`ptr\*(C'\fR and/or \f(CW\*(C`cnt\*(C'\fR. |
| 793 |
The application (or layer above) must ensure they are consistent. |
| 794 |
(Checking is allowed by the paranoid.) |
| 795 |
.SS Utilities |
| 796 |
.IX Subsection "Utilities" |
| 797 |
To ask for the next layer down use PerlIONext(PerlIO *f). |
| 798 |
.PP |
| 799 |
To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All |
| 800 |
this does is really just to check that the pointer is non-NULL and |
| 801 |
that the pointer behind that is non-NULL.) |
| 802 |
.PP |
| 803 |
PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words, |
| 804 |
the \f(CW\*(C`PerlIOl*\*(C'\fR pointer. |
| 805 |
.PP |
| 806 |
PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type. |
| 807 |
.PP |
| 808 |
Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either |
| 809 |
calls the \fIcallback\fR from the functions of the layer \fIf\fR (just by |
| 810 |
the name of the IO function, like "Read") with the \fIargs\fR, or if |
| 811 |
there is no such callback, calls the \fIbase\fR version of the callback |
| 812 |
with the same args, or if the f is invalid, set errno to EBADF and |
| 813 |
return \fIfailure\fR. |
| 814 |
.PP |
| 815 |
Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls |
| 816 |
the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, |
| 817 |
or if there is no such callback, set errno to EINVAL. Or if the f is |
| 818 |
invalid, set errno to EBADF and return \fIfailure\fR. |
| 819 |
.PP |
| 820 |
Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls |
| 821 |
the \fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, |
| 822 |
or if there is no such callback, calls the \fIbase\fR version of the |
| 823 |
callback with the same args, or if the f is invalid, set errno to |
| 824 |
EBADF. |
| 825 |
.PP |
| 826 |
Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the |
| 827 |
\&\fIcallback\fR of the functions of the layer \fIf\fR with the \fIargs\fR, or if |
| 828 |
there is no such callback, set errno to EINVAL. Or if the f is |
| 829 |
invalid, set errno to EBADF. |
| 830 |
.SS "Implementing PerlIO Layers" |
| 831 |
.IX Subsection "Implementing PerlIO Layers" |
| 832 |
If you find the implementation document unclear or not sufficient, |
| 833 |
look at the existing PerlIO layer implementations, which include: |
| 834 |
.IP \(bu 4 |
| 835 |
C implementations |
| 836 |
.Sp |
| 837 |
The \fIperlio.c\fR and \fIperliol.h\fR in the Perl core implement the |
| 838 |
"unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending" |
| 839 |
layers, and also the "mmap" and "win32" layers if applicable. |
| 840 |
(The "win32" is currently unfinished and unused, to see what is used |
| 841 |
instead in Win32, see "Querying the layers of filehandles" in PerlIO .) |
| 842 |
.Sp |
| 843 |
PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core. |
| 844 |
.Sp |
| 845 |
PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN. |
| 846 |
.IP \(bu 4 |
| 847 |
Perl implementations |
| 848 |
.Sp |
| 849 |
PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN. |
| 850 |
.PP |
| 851 |
If you are creating a PerlIO layer, you may want to be lazy, in other |
| 852 |
words, implement only the methods that interest you. The other methods |
| 853 |
you can either replace with the "blank" methods |
| 854 |
.PP |
| 855 |
.Vb 2 |
| 856 |
\& PerlIOBase_noop_ok |
| 857 |
\& PerlIOBase_noop_fail |
| 858 |
.Ve |
| 859 |
.PP |
| 860 |
(which do nothing, and return zero and \-1, respectively) or for |
| 861 |
certain methods you may assume a default behaviour by using a NULL |
| 862 |
method. The Open method looks for help in the 'parent' layer. |
| 863 |
The following table summarizes the behaviour: |
| 864 |
.PP |
| 865 |
.Vb 1 |
| 866 |
\& method behaviour with NULL |
| 867 |
\& |
| 868 |
\& Clearerr PerlIOBase_clearerr |
| 869 |
\& Close PerlIOBase_close |
| 870 |
\& Dup PerlIOBase_dup |
| 871 |
\& Eof PerlIOBase_eof |
| 872 |
\& Error PerlIOBase_error |
| 873 |
\& Fileno PerlIOBase_fileno |
| 874 |
\& Fill FAILURE |
| 875 |
\& Flush SUCCESS |
| 876 |
\& Getarg SUCCESS |
| 877 |
\& Get_base FAILURE |
| 878 |
\& Get_bufsiz FAILURE |
| 879 |
\& Get_cnt FAILURE |
| 880 |
\& Get_ptr FAILURE |
| 881 |
\& Open INHERITED |
| 882 |
\& Popped SUCCESS |
| 883 |
\& Pushed SUCCESS |
| 884 |
\& Read PerlIOBase_read |
| 885 |
\& Seek FAILURE |
| 886 |
\& Set_cnt FAILURE |
| 887 |
\& Set_ptrcnt FAILURE |
| 888 |
\& Setlinebuf PerlIOBase_setlinebuf |
| 889 |
\& Tell FAILURE |
| 890 |
\& Unread PerlIOBase_unread |
| 891 |
\& Write FAILURE |
| 892 |
\& |
| 893 |
\& FAILURE Set errno (to EINVAL in Unixish, to LIB$_INVARG in VMS) |
| 894 |
\& and return \-1 (for numeric return values) or NULL (for |
| 895 |
\& pointers) |
| 896 |
\& INHERITED Inherited from the layer below |
| 897 |
\& SUCCESS Return 0 (for numeric return values) or a pointer |
| 898 |
.Ve |
| 899 |
.SS "Core Layers" |
| 900 |
.IX Subsection "Core Layers" |
| 901 |
The file \f(CW\*(C`perlio.c\*(C'\fR provides the following layers: |
| 902 |
.IP """unix""" 4 |
| 903 |
.IX Item """unix""" |
| 904 |
A basic non-buffered layer which calls Unix/POSIX \f(CWread()\fR, \f(CWwrite()\fR, |
| 905 |
\&\f(CWlseek()\fR, \f(CWclose()\fR. No buffering. Even on platforms that distinguish |
| 906 |
between O_TEXT and O_BINARY this layer is always O_BINARY. |
| 907 |
.IP """perlio""" 4 |
| 908 |
.IX Item """perlio""" |
| 909 |
A very complete generic buffering layer which provides the whole of |
| 910 |
PerlIO API. It is also intended to be used as a "base class" for other |
| 911 |
layers. (For example its \f(CWRead()\fR method is implemented in terms of |
| 912 |
the \f(CWGet_cnt()\fR/\f(CWGet_ptr()\fR/\f(CWSet_ptrcnt()\fR methods). |
| 913 |
.Sp |
| 914 |
"perlio" over "unix" provides a complete replacement for stdio as seen |
| 915 |
via PerlIO API. This is the default for USE_PERLIO when system's stdio |
| 916 |
does not permit perl's "fast gets" access, and which do not |
| 917 |
distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR. |
| 918 |
.IP """stdio""" 4 |
| 919 |
.IX Item """stdio""" |
| 920 |
A layer which provides the PerlIO API via the layer scheme, but |
| 921 |
implements it by calling system's stdio. This is (currently) the default |
| 922 |
if system's stdio provides sufficient access to allow perl's "fast gets" |
| 923 |
access and which do not distinguish between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR. |
| 924 |
.IP """crlf""" 4 |
| 925 |
.IX Item """crlf""" |
| 926 |
A layer derived using "perlio" as a base class. It provides Win32\-like |
| 927 |
"\en" to CR,LF translation. Can either be applied above "perlio" or serve |
| 928 |
as the buffer layer itself. "crlf" over "unix" is the default if system |
| 929 |
distinguishes between \f(CW\*(C`O_TEXT\*(C'\fR and \f(CW\*(C`O_BINARY\*(C'\fR opens. (At some point |
| 930 |
"unix" will be replaced by a "native" Win32 IO layer on that platform, |
| 931 |
as Win32's read/write layer has various drawbacks.) The "crlf" layer is |
| 932 |
a reasonable model for a layer which transforms data in some way. |
| 933 |
.IP """mmap""" 4 |
| 934 |
.IX Item """mmap""" |
| 935 |
If Configure detects \f(CWmmap()\fR functions this layer is provided (with |
| 936 |
"perlio" as a "base") which does "read" operations by \fBmmap()\fRing the |
| 937 |
file. Performance improvement is marginal on modern systems, so it is |
| 938 |
mainly there as a proof of concept. It is likely to be unbundled from |
| 939 |
the core at some point. The "mmap" layer is a reasonable model for a |
| 940 |
minimalist "derived" layer. |
| 941 |
.IP """pending""" 4 |
| 942 |
.IX Item """pending""" |
| 943 |
An "internal" derivative of "perlio" which can be used to provide |
| 944 |
\&\fBUnread()\fR function for layers which have no buffer or cannot be |
| 945 |
bothered. (Basically this layer's \f(CWFill()\fR pops itself off the stack |
| 946 |
and so resumes reading from layer below.) |
| 947 |
.IP """raw""" 4 |
| 948 |
.IX Item """raw""" |
| 949 |
A dummy layer which never exists on the layer stack. Instead when |
| 950 |
"pushed" it actually pops the stack removing itself, it then calls |
| 951 |
Binmode function table entry on all the layers in the stack \- normally |
| 952 |
this (via PerlIOBase_binmode) removes any layers which do not have |
| 953 |
\&\f(CW\*(C`PERLIO_K_RAW\*(C'\fR bit set. Layers can modify that behaviour by defining |
| 954 |
their own Binmode entry. |
| 955 |
.IP """utf8""" 4 |
| 956 |
.IX Item """utf8""" |
| 957 |
Another dummy layer. When pushed it pops itself and sets the |
| 958 |
\&\f(CW\*(C`PERLIO_F_UTF8\*(C'\fR flag on the layer which was (and now is once more) |
| 959 |
the top of the stack. |
| 960 |
.PP |
| 961 |
In addition \fIperlio.c\fR also provides a number of \f(CWPerlIOBase_xxxx()\fR |
| 962 |
functions which are intended to be used in the table slots of classes |
| 963 |
which do not need to do anything special for a particular method. |
| 964 |
.SS "Extension Layers" |
| 965 |
.IX Subsection "Extension Layers" |
| 966 |
Layers can be made available by extension modules. When an unknown layer |
| 967 |
is encountered the PerlIO code will perform the equivalent of : |
| 968 |
.PP |
| 969 |
.Vb 1 |
| 970 |
\& use PerlIO \*(Aqlayer\*(Aq; |
| 971 |
.Ve |
| 972 |
.PP |
| 973 |
Where \fIlayer\fR is the unknown layer. \fIPerlIO.pm\fR will then attempt to: |
| 974 |
.PP |
| 975 |
.Vb 1 |
| 976 |
\& require PerlIO::layer; |
| 977 |
.Ve |
| 978 |
.PP |
| 979 |
If after that process the layer is still not defined then the \f(CW\*(C`open\*(C'\fR |
| 980 |
will fail. |
| 981 |
.PP |
| 982 |
The following extension layers are bundled with perl: |
| 983 |
.IP """:encoding""" 4 |
| 984 |
.IX Item """:encoding""" |
| 985 |
.Vb 1 |
| 986 |
\& use Encoding; |
| 987 |
.Ve |
| 988 |
.Sp |
| 989 |
makes this layer available, although \fIPerlIO.pm\fR "knows" where to |
| 990 |
find it. It is an example of a layer which takes an argument as it is |
| 991 |
called thus: |
| 992 |
.Sp |
| 993 |
.Vb 1 |
| 994 |
\& open( $fh, "<:encoding(iso\-8859\-7)", $pathname ); |
| 995 |
.Ve |
| 996 |
.IP """:scalar""" 4 |
| 997 |
.IX Item """:scalar""" |
| 998 |
Provides support for reading data from and writing data to a scalar. |
| 999 |
.Sp |
| 1000 |
.Vb 1 |
| 1001 |
\& open( $fh, "+<:scalar", \e$scalar ); |
| 1002 |
.Ve |
| 1003 |
.Sp |
| 1004 |
When a handle is so opened, then reads get bytes from the string value |
| 1005 |
of \fR\f(CI$scalar\fR\fI\fR, and writes change the value. In both cases the position |
| 1006 |
in \fI\fR\f(CI$scalar\fR\fI\fR starts as zero but can be altered via \f(CW\*(C`seek\*(C'\fR, and |
| 1007 |
determined via \f(CW\*(C`tell\*(C'\fR. |
| 1008 |
.Sp |
| 1009 |
Please note that this layer is implied when calling \fBopen()\fR thus: |
| 1010 |
.Sp |
| 1011 |
.Vb 1 |
| 1012 |
\& open( $fh, "+<", \e$scalar ); |
| 1013 |
.Ve |
| 1014 |
.IP """:via""" 4 |
| 1015 |
.IX Item """:via""" |
| 1016 |
Provided to allow layers to be implemented as Perl code. For instance: |
| 1017 |
.Sp |
| 1018 |
.Vb 2 |
| 1019 |
\& use PerlIO::via::StripHTML; |
| 1020 |
\& open( my $fh, "<:via(StripHTML)", "index.html" ); |
| 1021 |
.Ve |
| 1022 |
.Sp |
| 1023 |
See PerlIO::via for details. |
| 1024 |
.SH TODO |
| 1025 |
.IX Header "TODO" |
| 1026 |
Things that need to be done to improve this document. |
| 1027 |
.IP \(bu 4 |
| 1028 |
Explain how to make a valid fh without going through \fBopen()\fR(i.e. apply |
| 1029 |
a layer). For example if the file is not opened through perl, but we |
| 1030 |
want to get back a fh, like it was opened by Perl. |
| 1031 |
.Sp |
| 1032 |
How PerlIO_apply_layera fits in, where its docs, was it made public? |
| 1033 |
.Sp |
| 1034 |
Currently the example could be something like this: |
| 1035 |
.Sp |
| 1036 |
.Vb 8 |
| 1037 |
\& PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...) |
| 1038 |
\& { |
| 1039 |
\& char *mode; /* "w", "r", etc */ |
| 1040 |
\& const char *layers = ":APR"; /* the layer name */ |
| 1041 |
\& PerlIO *f = PerlIO_allocate(aTHX); |
| 1042 |
\& if (!f) { |
| 1043 |
\& return NULL; |
| 1044 |
\& } |
| 1045 |
\& |
| 1046 |
\& PerlIO_apply_layers(aTHX_ f, mode, layers); |
| 1047 |
\& |
| 1048 |
\& if (f) { |
| 1049 |
\& PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR); |
| 1050 |
\& /* fill in the st struct, as in _open() */ |
| 1051 |
\& st\->file = file; |
| 1052 |
\& PerlIOBase(f)\->flags |= PERLIO_F_OPEN; |
| 1053 |
\& |
| 1054 |
\& return f; |
| 1055 |
\& } |
| 1056 |
\& return NULL; |
| 1057 |
\& } |
| 1058 |
.Ve |
| 1059 |
.IP \(bu 4 |
| 1060 |
fix/add the documentation in places marked as XXX. |
| 1061 |
.IP \(bu 4 |
| 1062 |
The handling of errors by the layer is not specified. e.g. when $! |
| 1063 |
should be set explicitly, when the error handling should be just |
| 1064 |
delegated to the top layer. |
| 1065 |
.Sp |
| 1066 |
Probably give some hints on using \fBSETERRNO()\fR or pointers to where they |
| 1067 |
can be found. |
| 1068 |
.IP \(bu 4 |
| 1069 |
I think it would help to give some concrete examples to make it easier |
| 1070 |
to understand the API. Of course I agree that the API has to be |
| 1071 |
concise, but since there is no second document that is more of a |
| 1072 |
guide, I think that it'd make it easier to start with the doc which is |
| 1073 |
an API, but has examples in it in places where things are unclear, to |
| 1074 |
a person who is not a PerlIO guru (yet). |