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