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