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