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