Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perliol.1

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