a few typo fixes
[p5sagit/p5-mst-13.2.git] / pod / perliol.pod
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
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).
17
18 =head2 History and Background
19
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 extensions switched to using it, so the API is mostly fixed to
23 maintain (source) compatibility.
24
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.
28
29 =head2 Layers vs Disciplines
30
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.
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
56 A C<PerlIOl *> is a pointer 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".
63
64 It should be noted that because of the double indirection in a C<PerlIO *>,
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.
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
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:
84
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
123
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:
128
129 =over 4
130
131 =item 1.
132
133 Opening and setup functions
134
135 =item 2.
136
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.
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 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.
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.
194
195 The above is roughly equivalent to a "stdio" buffered stream, but with
196 much more flexibility:
197
198 =over 4
199
200 =item *
201
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.
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.
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 between 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.
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
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
233 layers.
234
235 =over 4
236
237 =item PERLIO_F_EOF
238
239 End of file.
240
241 =item PERLIO_F_CANWRITE
242
243 Writes are permitted, i.e. opened as "w" or "r+" or "a", etc.
244
245 =item  PERLIO_F_CANREAD
246
247 Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick).
248
249 =item PERLIO_F_ERROR
250
251 An error has occurred (for C<PerlIO_error()>)
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
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
266 flag rather than add/remove layers if the C<PERLIO_K_CANCRLF> bit is set
267 for the layers class.
268
269 =item PERLIO_F_UTF8
270
271 Data written to this layer should be UTF-8 encoded; data provided
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
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.
295
296 =item PERLIO_F_TEMP
297
298 File has been C<unlink()>ed, or should be deleted on C<close()>.
299
300 =item PERLIO_F_OPEN
301
302 Handle is open.
303
304 =item PERLIO_F_FASTGETS
305
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 existence of the function(s) in the table. However a class that
309 normally provides that interface may need to avoid it on a
310 particular instance. The "pending" layer needs to do this when
311 it is pushed above a layer which does not support the interface.
312 (Perl's C<sv_gets()> does not expect the streams fast C<gets> behaviour
313 to change during one "get".)
314
315 =back
316
317 =head2 Methods in Detail
318
319 =over 4
320
321 =item  IV               (*Pushed)(PerlIO *f,const char *mode, SV *arg);
322
323 The only absolutely 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>
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.
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).
330
331 =item  IV               (*Popped)(PerlIO *f);
332
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.
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 permitted. 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 itself 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 a 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 normally 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 descriptor for the handle. Normally
398 C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
399 for this.
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).
405 C<PerlIOBuf_read()> may be suitable for derived classes which provide
406 "fast gets" methods.
407
408 =item  SSize_t  (*Unread)(PerlIO *f, const void *vbuf, Size_t count);
409
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.
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
421 Position the file pointer. Should normally call its own C<Flush> method and
422 then the C<Seek> method of next layer down.
423
424 =item  Off_t            (*Tell)(PerlIO *f);
425
426 Return the file pointer. May be based on layers cached concept of
427 position to avoid overhead.
428
429 =item  IV               (*Close)(PerlIO *f);
430
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.
435
436 =item  IV               (*Flush)(PerlIO *f);
437
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 from below but not actually consumed.
441 (Should perhaps C<Unread()> such data to the lower layer.)
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
449 Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
450
451 =item  IV               (*Error)(PerlIO *f);
452
453 Return error indicator. C<PerlIOBase_error()> is normally sufficient.
454
455 =item  void             (*Clearerr)(PerlIO *f);
456
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.
459
460 =item  void             (*Setlinebuf)(PerlIO *f);
461
462 Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
463 PERLIO_F_LINEBUF flag and is normally sufficient.
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
472 Return the number of bytes that last C<Fill()> put in the buffer.
473
474 =item  STDCHAR *        (*Get_ptr)(PerlIO *f);
475
476 Return the current read pointer relative to this layer's buffer.
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
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.
502
503 =item "perlio"
504
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).
509
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>.
514
515 =item "stdio"
516
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>.
521
522 =item "crlf"
523
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.
531
532 =item "mmap"
533
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.
540
541 =item "pending"
542
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.)
547
548 =item "raw"
549
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.
553
554 =item "utf8"
555
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.
559
560 =back
561
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.
565
566 =head2 Extension Layers
567
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:
580
581 =over 4
582
583 =item ":encoding"
584
585    use Encoding;
586
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:
589
590    open($fh,"<:encoding(iso-8859-7)",$pathname)
591
592 =item ":Scalar"
593
594 Provides support for
595
596    open($fh,"...",\$scalar)
597
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
608
609 =cut
610
611
612