Commit | Line | Data |
---|---|---|
50b80e25 NIS |
1 | |
2 | =head1 NAME | |
3 | ||
4 | perliol - C API for Perl's implementation of IO in Layers. | |
5 | ||
6 | =head1 SYNOPSIS | |
7 | ||
8 | /* Defining a layer ... */ | |
9 | #include <perliol.h> | |
10 | ||
11 | ||
12 | =head1 DESCRIPTION | |
13 | ||
9d799145 NIS |
14 | This document describes the behavior and implementation of the PerlIO |
15 | abstraction described in L<perlapio> when C<USE_PERLIO> is defined (and | |
16 | C<USE_SFIO> is not). | |
50b80e25 NIS |
17 | |
18 | =head2 History and Background | |
19 | ||
9d799145 NIS |
20 | The PerlIO abstraction was introduced in perl5.003_02 but languished as |
21 | just an abstraction until perl5.7.0. However during that time a number | |
22 | of perl extentions switched to using it, so the API is mostly fixed to | |
23 | maintain (source) compatibility. | |
50b80e25 | 24 | |
9d799145 NIS |
25 | The aim of the implementation is to provide the PerlIO API in a flexible |
26 | and platform neutral manner. It is also a trial of an "Object Oriented | |
27 | C, with vtables" approach which may be applied to perl6. | |
50b80e25 NIS |
28 | |
29 | =head2 Layers vs Disciplines | |
30 | ||
9d799145 NIS |
31 | Initial discussion of the ability to modify IO streams behaviour used |
32 | the term "discipline" for the entities which were added. This came (I | |
33 | believe) from the use of the term in "sfio", which in turn borrowed it | |
34 | from "line disciplines" on Unix terminals. However, this document (and | |
35 | the C code) uses the term "layer". | |
36 | ||
37 | This is, I hope, a natural term given the implementation, and should avoid | |
38 | connotations that are inherent in earlier uses of "discipline" for things | |
39 | which are rather different. | |
50b80e25 NIS |
40 | |
41 | =head2 Data Structures | |
42 | ||
43 | The basic data structure is a PerlIOl: | |
44 | ||
45 | typedef struct _PerlIO PerlIOl; | |
46 | typedef struct _PerlIO_funcs PerlIO_funcs; | |
47 | typedef PerlIOl *PerlIO; | |
48 | ||
49 | struct _PerlIO | |
50 | { | |
51 | PerlIOl * next; /* Lower layer */ | |
52 | PerlIO_funcs * tab; /* Functions for this layer */ | |
53 | IV flags; /* Various flags for state */ | |
54 | }; | |
55 | ||
9d799145 NIS |
56 | A C<PerlIOl *> is a pointer to to the struct, and the I<application> level |
57 | C<PerlIO *> is a pointer to a C<PerlIOl *> - i.e. a pointer to a pointer to | |
58 | the struct. This allows the application level C<PerlIO *> to remain | |
59 | constant while the actual C<PerlIOl *> underneath changes. (Compare perl's | |
60 | C<SV *> which remains constant while its C<sv_any> field changes as the | |
61 | scalar's type changes.) An IO stream is then in general represented as a | |
62 | pointer to this linked-list of "layers". | |
50b80e25 | 63 | |
9d799145 | 64 | It should be noted that because of the double indirection in a C<PerlIO *>, |
11e1c8f2 PP |
65 | a C<< &(perlio-E<gt>next) >> "is" a C<PerlIO *>, and so to some degree |
66 | at least one layer can use the "standard" API on the next layer down. | |
50b80e25 NIS |
67 | |
68 | A "layer" is composed of two parts: | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item 1. The functions and attributes of the "layer class". | |
73 | ||
74 | =item 2. The per-instance data for a particular handle. | |
75 | ||
76 | =back | |
77 | ||
78 | =head2 Functions and Attributes | |
79 | ||
9d799145 NIS |
80 | The functions and attributes are accessed via the "tab" (for table) |
81 | member of C<PerlIOl>. The functions (methods of the layer "class") are | |
82 | fixed, and are defined by the C<PerlIO_funcs> type. They are broadly the | |
83 | same as the public C<PerlIO_xxxxx> functions: | |
50b80e25 | 84 | |
b76cc8ba NIS |
85 | struct _PerlIO_funcs |
86 | { | |
87 | char * name; | |
88 | Size_t size; | |
89 | IV kind; | |
90 | IV (*Pushed)(PerlIO *f,const char *mode,SV *arg); | |
91 | IV (*Popped)(PerlIO *f); | |
92 | PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, | |
93 | AV *layers, IV n, | |
94 | const char *mode, | |
95 | int fd, int imode, int perm, | |
96 | PerlIO *old, | |
97 | int narg, SV **args); | |
98 | SV * (*Getarg)(PerlIO *f); | |
99 | IV (*Fileno)(PerlIO *f); | |
100 | /* Unix-like functions - cf sfio line disciplines */ | |
101 | SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count); | |
102 | SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count); | |
103 | SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); | |
104 | IV (*Seek)(PerlIO *f, Off_t offset, int whence); | |
105 | Off_t (*Tell)(PerlIO *f); | |
106 | IV (*Close)(PerlIO *f); | |
107 | /* Stdio-like buffered IO functions */ | |
108 | IV (*Flush)(PerlIO *f); | |
109 | IV (*Fill)(PerlIO *f); | |
110 | IV (*Eof)(PerlIO *f); | |
111 | IV (*Error)(PerlIO *f); | |
112 | void (*Clearerr)(PerlIO *f); | |
113 | void (*Setlinebuf)(PerlIO *f); | |
114 | /* Perl's snooping functions */ | |
115 | STDCHAR * (*Get_base)(PerlIO *f); | |
116 | Size_t (*Get_bufsiz)(PerlIO *f); | |
117 | STDCHAR * (*Get_ptr)(PerlIO *f); | |
118 | SSize_t (*Get_cnt)(PerlIO *f); | |
119 | void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt); | |
120 | }; | |
121 | ||
122 | ||
50b80e25 | 123 | |
9d799145 NIS |
124 | The first few members of the struct give a "name" for the layer, the |
125 | size to C<malloc> for the per-instance data, and some flags which are | |
126 | attributes of the class as whole (such as whether it is a buffering | |
127 | layer), then follow the functions which fall into four basic groups: | |
50b80e25 NIS |
128 | |
129 | =over 4 | |
130 | ||
aa500c9e | 131 | =item 1. |
50b80e25 | 132 | |
aa500c9e | 133 | Opening and setup functions |
50b80e25 | 134 | |
aa500c9e | 135 | =item 2. |
50b80e25 | 136 | |
aa500c9e RB |
137 | Basic IO operations |
138 | ||
139 | =item 3. | |
140 | ||
141 | Stdio class buffering options. | |
142 | ||
143 | =item 4. | |
144 | ||
145 | Functions to support Perl's traditional "fast" access to the buffer. | |
50b80e25 NIS |
146 | |
147 | =back | |
148 | ||
149 | A layer does not have to implement all the functions, but the whole table has | |
150 | to be present. Unimplemented slots can be NULL (which will will result in an error | |
151 | when called) or can be filled in with stubs to "inherit" behaviour from | |
152 | a "base class". This "inheritance" is fixed for all instances of the layer, | |
153 | but as the layer chooses which stubs to populate the table, limited | |
154 | "multiple inheritance" is possible. | |
155 | ||
156 | =head2 Per-instance Data | |
157 | ||
158 | The per-instance data are held in memory beyond the basic PerlIOl struct, | |
159 | by making a PerlIOl the first member of the layer's struct thus: | |
160 | ||
161 | typedef struct | |
162 | { | |
163 | struct _PerlIO base; /* Base "class" info */ | |
164 | STDCHAR * buf; /* Start of buffer */ | |
165 | STDCHAR * end; /* End of valid part of buffer */ | |
166 | STDCHAR * ptr; /* Current position in buffer */ | |
167 | Off_t posn; /* Offset of buf into the file */ | |
168 | Size_t bufsiz; /* Real size of buffer */ | |
169 | IV oneword; /* Emergency buffer */ | |
170 | } PerlIOBuf; | |
171 | ||
172 | In this way (as for perl's scalars) a pointer to a PerlIOBuf can be treated | |
173 | as a pointer to a PerlIOl. | |
174 | ||
175 | =head2 Layers in action. | |
176 | ||
177 | table perlio unix | |
178 | | | | |
179 | +-----------+ +----------+ +--------+ | |
180 | PerlIO ->| |--->| next |--->| NULL | | |
181 | +-----------+ +----------+ +--------+ | |
182 | | | | buffer | | fd | | |
183 | +-----------+ | | +--------+ | |
184 | | | +----------+ | |
185 | ||
186 | ||
187 | The above attempts to show how the layer scheme works in a simple case. | |
9d799145 NIS |
188 | The application's C<PerlIO *> points to an entry in the table(s) |
189 | representing open (allocated) handles. For example the first three slots | |
190 | in the table correspond to C<stdin>,C<stdout> and C<stderr>. The table | |
191 | in turn points to the current "top" layer for the handle - in this case | |
192 | an instance of the generic buffering layer "perlio". That layer in turn | |
193 | points to the next layer down - in this case the lowlevel "unix" layer. | |
50b80e25 | 194 | |
9d799145 NIS |
195 | The above is roughly equivalent to a "stdio" buffered stream, but with |
196 | much more flexibility: | |
50b80e25 NIS |
197 | |
198 | =over 4 | |
199 | ||
200 | =item * | |
201 | ||
9d799145 NIS |
202 | If Unix level C<read>/C<write>/C<lseek> is not appropriate for (say) |
203 | sockets then the "unix" layer can be replaced (at open time or even | |
204 | dynamically) with a "socket" layer. | |
50b80e25 NIS |
205 | |
206 | =item * | |
207 | ||
208 | Different handles can have different buffering schemes. The "top" layer | |
209 | could be the "mmap" layer if reading disk files was quicker using C<mmap> | |
210 | than C<read>. An "unbuffered" stream can be implemented simply by | |
211 | not having a buffer layer. | |
212 | ||
213 | =item * | |
214 | ||
215 | Extra layers can be inserted to process the data as it flows through. | |
9d799145 NIS |
216 | This was the driving need for including the scheme in perl 5.7.0+ - we |
217 | needed a mechanism to allow data to be translated bewteen perl's | |
218 | internal encoding (conceptually at least Unicode as UTF-8), and the | |
219 | "native" format used by the system. This is provided by the | |
220 | ":encoding(xxxx)" layer which typically sits above the buffering layer. | |
50b80e25 NIS |
221 | |
222 | =item * | |
223 | ||
224 | A layer can be added that does "\n" to CRLF translation. This layer can be used | |
225 | on any platform, not just those that normally do such things. | |
226 | ||
227 | =back | |
228 | ||
229 | =head2 Per-instance flag bits | |
230 | ||
9d799145 NIS |
231 | The generic flag bits are a hybrid of C<O_XXXXX> style flags deduced from |
232 | the mode string passed to C<PerlIO_open()>, and state bits for typical buffer | |
50b80e25 NIS |
233 | layers. |
234 | ||
9d799145 | 235 | =over 4 |
50b80e25 NIS |
236 | |
237 | =item PERLIO_F_EOF | |
238 | ||
239 | End of file. | |
240 | ||
241 | =item PERLIO_F_CANWRITE | |
242 | ||
3039a93d | 243 | Writes are permitted, i.e. opened as "w" or "r+" or "a", etc. |
50b80e25 NIS |
244 | |
245 | =item PERLIO_F_CANREAD | |
246 | ||
3039a93d | 247 | Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick). |
50b80e25 NIS |
248 | |
249 | =item PERLIO_F_ERROR | |
250 | ||
9d799145 | 251 | An error has occured (for C<PerlIO_error()>) |
50b80e25 NIS |
252 | |
253 | =item PERLIO_F_TRUNCATE | |
254 | ||
255 | Truncate file suggested by open mode. | |
256 | ||
257 | =item PERLIO_F_APPEND | |
258 | ||
259 | All writes should be appends. | |
260 | ||
261 | =item PERLIO_F_CRLF | |
262 | ||
11e1c8f2 PP |
263 | Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF |
264 | mapped to "\n" for input. Normally the provided "crlf" layer is the only | |
265 | layer that need bother about this. C<PerlIO_binmode()> will mess with this | |
9d799145 NIS |
266 | flag rather than add/remove layers if the C<PERLIO_K_CANCRLF> bit is set |
267 | for the layers class. | |
50b80e25 NIS |
268 | |
269 | =item PERLIO_F_UTF8 | |
270 | ||
3039a93d | 271 | Data written to this layer should be UTF-8 encoded; data provided |
50b80e25 NIS |
272 | by this layer should be considered UTF-8 encoded. Can be set on any layer |
273 | by ":utf8" dummy layer. Also set on ":encoding" layer. | |
274 | ||
275 | =item PERLIO_F_UNBUF | |
276 | ||
277 | Layer is unbuffered - i.e. write to next layer down should occur for | |
278 | each write to this layer. | |
279 | ||
280 | =item PERLIO_F_WRBUF | |
281 | ||
282 | The buffer for this layer currently holds data written to it but not sent | |
283 | to next layer. | |
284 | ||
285 | =item PERLIO_F_RDBUF | |
286 | ||
287 | The buffer for this layer currently holds unconsumed data read from | |
288 | layer below. | |
289 | ||
290 | =item PERLIO_F_LINEBUF | |
291 | ||
9d799145 NIS |
292 | Layer is line buffered. Write data should be passed to next layer down |
293 | whenever a "\n" is seen. Any data beyond the "\n" should then be | |
294 | processed. | |
50b80e25 NIS |
295 | |
296 | =item PERLIO_F_TEMP | |
297 | ||
9d799145 | 298 | File has been C<unlink()>ed, or should be deleted on C<close()>. |
50b80e25 NIS |
299 | |
300 | =item PERLIO_F_OPEN | |
301 | ||
302 | Handle is open. | |
303 | ||
304 | =item PERLIO_F_FASTGETS | |
305 | ||
9d799145 NIS |
306 | This instance of this layer supports the "fast C<gets>" interface. |
307 | Normally set based on C<PERLIO_K_FASTGETS> for the class and by the | |
308 | existance of the function(s) in the table. However a class that | |
50b80e25 NIS |
309 | normally provides that interface may need to avoid it on a |
310 | particular instance. The "pending" layer needs to do this when | |
9d799145 NIS |
311 | it is pushed above an layer which does not support the interface. |
312 | (Perl's C<sv_gets()> does not expect the streams fast C<gets> behaviour | |
50b80e25 NIS |
313 | to change during one "get".) |
314 | ||
315 | =back | |
316 | ||
317 | =head2 Methods in Detail | |
318 | ||
319 | =over 4 | |
320 | ||
b76cc8ba | 321 | =item IV (*Pushed)(PerlIO *f,const char *mode, SV *arg); |
50b80e25 | 322 | |
b76cc8ba NIS |
323 | The only absoultely mandatory method. Called when the layer is pushed onto the stack. |
324 | The C<mode> argument may be NULL if this occurs post-open. The C<arg> will be non-C<NULL> | |
9d799145 NIS |
325 | if an argument string was passed. In most cases this should call |
326 | C<PerlIOBase_pushed()> to convert C<mode> into the appropriate | |
327 | C<PERLIO_F_XXXXX> flags in addition to any actions the layer itself takes. | |
b76cc8ba NIS |
328 | If a layer is not expecting an argument it need neither save the one passed to it, nor |
329 | provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument was un-expected). | |
50b80e25 NIS |
330 | |
331 | =item IV (*Popped)(PerlIO *f); | |
332 | ||
9d799145 NIS |
333 | Called when the layer is popped from the stack. A layer will normally be |
334 | popped after C<Close()> is called. But a layer can be popped without being | |
335 | closed if the program is dynamically managing layers on the stream. In | |
336 | such cases C<Popped()> should free any resources (buffers, translation | |
337 | tables, ...) not held directly in the layer's struct. | |
b76cc8ba NIS |
338 | It should also C<Unread()> any unconsumed data that has been read and buffered |
339 | from the layer below back to that layer, so that it can be re-provided to what | |
340 | ever is now above. | |
341 | ||
342 | =item PerlIO * (*Open)(...); | |
343 | ||
344 | The C<Open()> method has lots of arguments because it combines the functions | |
345 | of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>, C<PerlIO_fdopen> and C<PerlIO_reopen>. | |
346 | The full prototype is as follows: | |
347 | ||
348 | PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, | |
349 | AV *layers, IV n, | |
350 | const char *mode, | |
351 | int fd, int imode, int perm, | |
352 | PerlIO *old, | |
353 | int narg, SV **args); | |
354 | ||
355 | Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate a slot in the table and | |
356 | associate it with the layers information for the opened file, by calling C<PerlIO_push>. | |
357 | The I<layers> AV is an array of all the layers destined for the C<PerlIO *>, | |
358 | and any arguments passed to them, I<n> is the index into that array of the | |
359 | layer being called. The macro C<PerlIOArg> will return a (possibly C<NULL>) SV * | |
360 | for the argument passed to the layer. | |
361 | ||
362 | The I<mode> string is an "C<fopen()>-like" string which would match the regular | |
363 | expression C</^[I#]?[rwa]\+?[bt]?$/>. | |
364 | ||
365 | The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via special | |
366 | C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is C<sysopen> and that I<imode> and | |
367 | I<perm> should be passed to C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite | |
368 | and C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and writing/appending | |
369 | are permited. The C<'b'> suffix means file should be binary, and C<'t'> means it | |
370 | is text. (Binary/Text should be ignored by almost all layers and binary IO done, | |
371 | with PerlIO. The C<:crlf> layer should be pushed to handle the distinction.) | |
372 | ||
373 | If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl iteself does not use | |
374 | this (yet?) and semantics are a little vague. | |
375 | ||
376 | If I<fd> not negative then it is the numeric file descriptor I<fd>, which will | |
377 | be open in an manner compatible with the supplied mode string, the call is | |
378 | thus equivalent to C<PerlIO_fdopen>. In this case I<nargs> will be zero. | |
379 | ||
380 | If I<nargs> is greater than zero then it gives the number of arguments passed | |
381 | to C<open>, otherwise it will be 1 if for example C<PerlIO_open> was called. | |
382 | In simple cases SvPV(*args) is the pathname to open. | |
383 | ||
384 | Having said all that translation-only layers do not need to provide C<Open()> at all, | |
385 | but rather leave the opening to a lower level layer and wait to be "pushed". | |
386 | If a layer does provide C<Open()> it should normaly call the C<Open()> method | |
387 | of next layer down (if any) and then push itself on top if that succeeds. | |
388 | ||
389 | =item SV * (*Getarg)(PerlIO *f); | |
390 | ||
391 | Optional. If present should return an SV * representing the string argument | |
392 | passed to the layer when it was pushed. e.g. ":encoding(ascii)" would | |
393 | return an SvPV with value "ascii". | |
394 | ||
395 | =item IV (*Fileno)(PerlIO *f); | |
396 | ||
397 | Returns the Unix/Posix numeric file decriptor for the handle. Normally | |
398 | C<PerlIOBase_fileno()> (which just asks next layer down) will suffice | |
399 | for this. | |
50b80e25 NIS |
400 | |
401 | =item SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count); | |
402 | ||
403 | Basic read operation. Returns actual bytes read, or -1 on an error. | |
404 | Typically will call Fill and manipulate pointers (possibly via the API). | |
9d799145 NIS |
405 | C<PerlIOBuf_read()> may be suitable for derived classes which provide |
406 | "fast gets" methods. | |
50b80e25 NIS |
407 | |
408 | =item SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count); | |
409 | ||
9d799145 NIS |
410 | A superset of stdio's C<ungetc()>. Should arrange for future reads to |
411 | see the bytes in C<vbuf>. If there is no obviously better implementation | |
412 | then C<PerlIOBase_unread()> provides the function by pushing a "fake" | |
413 | "pending" layer above the calling layer. | |
50b80e25 NIS |
414 | |
415 | =item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); | |
416 | ||
417 | Basic write operation. Returns bytes written or -1 on an error. | |
418 | ||
419 | =item IV (*Seek)(PerlIO *f, Off_t offset, int whence); | |
420 | ||
9d799145 NIS |
421 | Position the file pointer. Should normally call its own C<Flush> method and |
422 | then the C<Seek> method of next layer down. | |
50b80e25 NIS |
423 | |
424 | =item Off_t (*Tell)(PerlIO *f); | |
425 | ||
9d799145 NIS |
426 | Return the file pointer. May be based on layers cached concept of |
427 | position to avoid overhead. | |
50b80e25 NIS |
428 | |
429 | =item IV (*Close)(PerlIO *f); | |
430 | ||
9d799145 NIS |
431 | Close the stream. Should normally call C<PerlIOBase_close()> to flush |
432 | itself and close layers below, and then deallocate any data structures | |
433 | (buffers, translation tables, ...) not held directly in the data | |
434 | structure. | |
50b80e25 NIS |
435 | |
436 | =item IV (*Flush)(PerlIO *f); | |
437 | ||
9d799145 NIS |
438 | Should make stream's state consistent with layers below. That is, any |
439 | buffered write data should be written, and file position of lower layers | |
440 | adjusted for data read fron below but not actually consumed. | |
b76cc8ba | 441 | (Should perhaps C<Unread()> such data to the lower layer.) |
50b80e25 NIS |
442 | |
443 | =item IV (*Fill)(PerlIO *f); | |
444 | ||
445 | The buffer for this layer should be filled (for read) from layer below. | |
446 | ||
447 | =item IV (*Eof)(PerlIO *f); | |
448 | ||
9d799145 | 449 | Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient. |
50b80e25 NIS |
450 | |
451 | =item IV (*Error)(PerlIO *f); | |
452 | ||
9d799145 | 453 | Return error indicator. C<PerlIOBase_error()> is normally sufficient. |
50b80e25 NIS |
454 | |
455 | =item void (*Clearerr)(PerlIO *f); | |
456 | ||
9d799145 NIS |
457 | Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()> |
458 | to set the C<PERLIO_F_XXXXX> flags, which may suffice. | |
50b80e25 NIS |
459 | |
460 | =item void (*Setlinebuf)(PerlIO *f); | |
461 | ||
b76cc8ba NIS |
462 | Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the |
463 | PERLIO_F_LINEBUF flag and is normally sufficient. | |
50b80e25 NIS |
464 | |
465 | =item STDCHAR * (*Get_base)(PerlIO *f); | |
466 | ||
467 | Allocate (if not already done so) the read buffer for this layer and | |
468 | return pointer to it. | |
469 | ||
470 | =item Size_t (*Get_bufsiz)(PerlIO *f); | |
471 | ||
9d799145 | 472 | Return the number of bytes that last C<Fill()> put in the buffer. |
50b80e25 NIS |
473 | |
474 | =item STDCHAR * (*Get_ptr)(PerlIO *f); | |
475 | ||
3039a93d | 476 | Return the current read pointer relative to this layer's buffer. |
50b80e25 NIS |
477 | |
478 | =item SSize_t (*Get_cnt)(PerlIO *f); | |
479 | ||
480 | Return the number of bytes left to be read in the current buffer. | |
481 | ||
482 | =item void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt); | |
483 | ||
484 | Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>. | |
485 | The application (or layer above) must ensure they are consistent. | |
486 | (Checking is allowed by the paranoid.) | |
487 | ||
488 | =back | |
489 | ||
490 | ||
491 | =head2 Core Layers | |
492 | ||
493 | The file C<perlio.c> provides the following layers: | |
494 | ||
495 | =over 4 | |
496 | ||
497 | =item "unix" | |
498 | ||
9d799145 NIS |
499 | A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>, |
500 | C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish | |
501 | between O_TEXT and O_BINARY this layer is always O_BINARY. | |
50b80e25 NIS |
502 | |
503 | =item "perlio" | |
504 | ||
9d799145 NIS |
505 | A very complete generic buffering layer which provides the whole of |
506 | PerlIO API. It is also intended to be used as a "base class" for other | |
507 | layers. (For example its C<Read()> method is implemented in terms of the | |
508 | C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods). | |
50b80e25 | 509 | |
9d799145 NIS |
510 | "perlio" over "unix" provides a complete replacement for stdio as seen |
511 | via PerlIO API. This is the default for USE_PERLIO when system's stdio | |
512 | does not permit perl's "fast gets" access, and which do not distinguish | |
513 | between C<O_TEXT> and C<O_BINARY>. | |
50b80e25 NIS |
514 | |
515 | =item "stdio" | |
516 | ||
9d799145 NIS |
517 | A layer which provides the PerlIO API via the layer scheme, but |
518 | implements it by calling system's stdio. This is (currently) the default | |
519 | if system's stdio provides sufficient access to allow perl's "fast gets" | |
520 | access and which do not distinguish between C<O_TEXT> and C<O_BINARY>. | |
50b80e25 NIS |
521 | |
522 | =item "crlf" | |
523 | ||
9d799145 NIS |
524 | A layer derived using "perlio" as a base class. It provides Win32-like |
525 | "\n" to CR,LF translation. Can either be applied above "perlio" or serve | |
526 | as the buffer layer itself. "crlf" over "unix" is the default if system | |
527 | distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point | |
528 | "unix" will be replaced by a "native" Win32 IO layer on that platform, | |
529 | as Win32's read/write layer has various drawbacks.) The "crlf" layer is | |
530 | a reasonable model for a layer which transforms data in some way. | |
50b80e25 NIS |
531 | |
532 | =item "mmap" | |
533 | ||
9d799145 NIS |
534 | If Configure detects C<mmap()> functions this layer is provided (with |
535 | "perlio" as a "base") which does "read" operations by mmap()ing the | |
536 | file. Performance improvement is marginal on modern systems, so it is | |
537 | mainly there as a proof of concept. It is likely to be unbundled from | |
538 | the core at some point. The "mmap" layer is a reasonable model for a | |
539 | minimalist "derived" layer. | |
50b80e25 NIS |
540 | |
541 | =item "pending" | |
542 | ||
9d799145 NIS |
543 | An "internal" derivative of "perlio" which can be used to provide |
544 | Unread() function for layers which have no buffer or cannot be bothered. | |
545 | (Basically this layer's C<Fill()> pops itself off the stack and so resumes | |
546 | reading from layer below.) | |
50b80e25 NIS |
547 | |
548 | =item "raw" | |
549 | ||
9d799145 NIS |
550 | A dummy layer which never exists on the layer stack. Instead when |
551 | "pushed" it actually pops the stack(!), removing itself, and any other | |
552 | layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set. | |
50b80e25 NIS |
553 | |
554 | =item "utf8" | |
555 | ||
9d799145 NIS |
556 | Another dummy layer. When pushed it pops itself and sets the |
557 | C<PERLIO_F_UTF8> flag on the layer which was (and now is once more) the top | |
558 | of the stack. | |
50b80e25 NIS |
559 | |
560 | =back | |
561 | ||
9d799145 NIS |
562 | In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()> |
563 | functions which are intended to be used in the table slots of classes | |
564 | which do not need to do anything special for a particular method. | |
50b80e25 NIS |
565 | |
566 | =head2 Extension Layers | |
567 | ||
b76cc8ba NIS |
568 | Layers can made available by extension modules. When an unknown layer is encountered |
569 | the PerlIO code will perform the equivalent of : | |
570 | ||
571 | use PerlIO 'layer'; | |
572 | ||
573 | Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to : | |
574 | ||
575 | require PerlIO::layer; | |
576 | ||
577 | If after that process the layer is still not defined then the C<open> will fail. | |
578 | ||
579 | The following extension layers are bundled with perl: | |
50b80e25 NIS |
580 | |
581 | =over 4 | |
582 | ||
b76cc8ba | 583 | =item ":encoding" |
50b80e25 NIS |
584 | |
585 | use Encoding; | |
586 | ||
b76cc8ba NIS |
587 | makes this layer available, although F<PerlIO.pm> "knows" where to find it. |
588 | It is an example of a layer which takes an argument as it is called thus: | |
50b80e25 NIS |
589 | |
590 | open($fh,"<:encoding(iso-8859-7)",$pathname) | |
591 | ||
b76cc8ba NIS |
592 | =item ":Scalar" |
593 | ||
594 | Provides support for | |
595 | ||
596 | open($fh,"...",\$scalar) | |
50b80e25 | 597 | |
b76cc8ba NIS |
598 | When a handle is so opened, then reads get bytes from the string value of I<$scalar>, |
599 | and writes change the value. In both cases the position in I<$scalar> starts as zero | |
600 | but can be altered via C<seek>, and determined via C<tell>. | |
601 | ||
602 | =item ":Object" or ":Perl" | |
603 | ||
604 | May be provided to allow layers to be implemented as perl code - implementation | |
605 | is being investigated. | |
606 | ||
607 | =back | |
50b80e25 NIS |
608 | |
609 | =cut | |
610 | ||
611 | ||
612 |