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 char * name;
 326
 327 The name of the layer whose open() method Perl should invoke on
 328 open().  For example if the layer is called APR, you will call:
 329
 330   open $fh, ">:APR", ...
 331
 332 and Perl knows that it has to invoke the PerlIOAPR_open() method
 333 implemented by the APR layer.
 334
 335 =item Size_t size;
 336
 337 The size of the per-instance data structure, e.g.:
 338
 339   sizeof(PerlIOAPR)
 340
 341 =item IV kind;
 342
 343  XXX: explain all the available flags here
 344
 345 =over 4
 346
 347 =item * PERLIO_K_BUFFERED
 348
 349 =item * PERLIO_K_CANCRLF
 350
 351 =item * PERLIO_K_FASTGETS
 352
 353 =item * PERLIO_K_MULTIARG
 354
 355 Used when the layer's open() accepts more arguments than usual. The
 356 extra arguments should come not before the C<MODE> argument. When this
 357 flag is used it's up to the layer to validate the args.
 358
 359 =item * PERLIO_K_RAW
 360
 361 =back
 362
 363 =item IV                (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
 364
 365 The only absolutely mandatory method. Called when the layer is pushed
 366 onto the stack.  The C<mode> argument may be NULL if this occurs
 367 post-open. The C<arg> will be non-C<NULL> if an argument string was
 368 passed. In most cases this should call C<PerlIOBase_pushed()> to
 369 convert C<mode> into the appropriate C<PERLIO_F_XXXXX> flags in
 370 addition to any actions the layer itself takes.  If a layer is not
 371 expecting an argument it need neither save the one passed to it, nor
 372 provide C<Getarg()> (it could perhaps C<Perl_warn> that the argument
 373 was un-expected).
 374
 375 Returns 0 on success. On failure returns -1 and should set errno.
 376
 377 =item  IV               (*Popped)(pTHX_ PerlIO *f);
 378
 379 Called when the layer is popped from the stack. A layer will normally
 380 be popped after C<Close()> is called. But a layer can be popped
 381 without being closed if the program is dynamically managing layers on
 382 the stream. In such cases C<Popped()> should free any resources
 383 (buffers, translation tables, ...) not held directly in the layer's
 384 struct.  It should also C<Unread()> any unconsumed data that has been
 385 read and buffered from the layer below back to that layer, so that it
 386 can be re-provided to what ever is now above.
 387
 388 Returns 0 on success and failure.
 389
 390 =item  PerlIO * (*Open)(...);
 391
 392 The C<Open()> method has lots of arguments because it combines the
 393 functions of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>,
 394 C<PerlIO_fdopen> and C<PerlIO_reopen>.  The full prototype is as
 395 follows:
 396
 397  PerlIO *       (*Open)(pTHX_ PerlIO_funcs *tab,
 398                         AV *layers, IV n,
 399                         const char *mode,
 400                         int fd, int imode, int perm,
 401                         PerlIO *old,
 402                         int narg, SV **args);
 403
 404 Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate
 405 a slot in the table and associate it with the layers information for
 406 the opened file, by calling C<PerlIO_push>.  The I<layers> AV is an
 407 array of all the layers destined for the C<PerlIO *>, and any
 408 arguments passed to them, I<n> is the index into that array of the
 409 layer being called. The macro C<PerlIOArg> will return a (possibly
 410 C<NULL>) SV * for the argument passed to the layer.
 411
 412 The I<mode> string is an "C<fopen()>-like" string which would match
 413 the regular expression C</^[I#]?[rwa]\+?[bt]?$/>.
 414
 415 The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via
 416 special C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is
 417 C<sysopen> and that I<imode> and I<perm> should be passed to
 418 C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite and
 419 C<'a'> means B<a>ppend. The C<'+'> suffix means that both reading and
 420 writing/appending are permitted. The C<'b'> suffix means file should
 421 be binary, and C<'t'> means it is text. (Binary/Text should be ignored
 422 by almost all layers and binary IO done, with PerlIO. The C<:crlf>
 423 layer should be pushed to handle the distinction.)
 424
 425 If I<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself
 426 does not use this (yet?) and semantics are a little vague.
 427
 428 If I<fd> not negative then it is the numeric file descriptor I<fd>,
 429 which will be open in a manner compatible with the supplied mode
 430 string, the call is thus equivalent to C<PerlIO_fdopen>. In this case
 431 I<nargs> will be zero.
 432
 433 If I<nargs> is greater than zero then it gives the number of arguments
 434 passed to C<open>, otherwise it will be 1 if for example
 435 C<PerlIO_open> was called.  In simple cases SvPV_nolen(*args) is the
 436 pathname to open.
 437
 438 Having said all that translation-only layers do not need to provide
 439 C<Open()> at all, but rather leave the opening to a lower level layer
 440 and wait to be "pushed".  If a layer does provide C<Open()> it should
 441 normally call the C<Open()> method of next layer down (if any) and
 442 then push itself on top if that succeeds.
 443
 444 Returns C<NULL> on failure.
 445
 446 =item SV *      (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
 447
 448 Optional. If present should return an SV * representing the string
 449 argument passed to the layer when it was
 450 pushed. e.g. ":encoding(ascii)" would return an SvPV with value
 451 "ascii". (I<param> and I<flags> arguments can be ignored in most
 452 cases)
 453
 454 =item IV        (*Fileno)(pTHX_ PerlIO *f);
 455
 456 Returns the Unix/Posix numeric file descriptor for the handle. Normally
 457 C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
 458 for this.
 459
 460 Returns -1 if the layer cannot provide such a file descriptor, or in
 461 the case of the error.
 462
 463 XXX: two possible results end up in -1, one is an error the other is
 464 not.
 465
 466 =item PerlIO *  (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
 467
 468 XXX: not documented
 469
 470 Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
 471
 472 =item  SSize_t  (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
 473
 474 Basic read operation.
 475
 476 Typically will call C<Fill> and manipulate pointers (possibly via the
 477 API).  C<PerlIOBuf_read()> may be suitable for derived classes which
 478 provide "fast gets" methods.
 479
 480 Returns actual bytes read, or -1 on an error.
 481
 482 =item  SSize_t  (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
 483
 484 A superset of stdio's C<ungetc()>. Should arrange for future reads to
 485 see the bytes in C<vbuf>. If there is no obviously better implementation
 486 then C<PerlIOBase_unread()> provides the function by pushing a "fake"
 487 "pending" layer above the calling layer.
 488
 489 Returns the number of unread chars.
 490
 491 =item  SSize_t  (*Write)(PerlIO *f, const void *vbuf, Size_t count);
 492
 493 Basic write operation.
 494
 495 Returns bytes written or -1 on an error.
 496
 497 =item  IV               (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
 498
 499 Position the file pointer. Should normally call its own C<Flush>
 500 method and then the C<Seek> method of next layer down.
 501
 502 Returns 0 on success, -1 on failure.
 503
 504 =item  Off_t            (*Tell)(pTHX_ PerlIO *f);
 505
 506 Return the file pointer. May be based on layers cached concept of
 507 position to avoid overhead.
 508
 509 Returns -1 on failure to get the file pointer.
 510
 511 =item  IV               (*Close)(pTHX_ PerlIO *f);
 512
 513 Close the stream. Should normally call C<PerlIOBase_close()> to flush
 514 itself and close layers below, and then deallocate any data structures
 515 (buffers, translation tables, ...) not  held directly in the data
 516 structure.
 517
 518 Returns 0 on success, -1 on failure.
 519
 520 =item  IV               (*Flush)(pTHX_ PerlIO *f);
 521
 522 Should make stream's state consistent with layers below. That is, any
 523 buffered write data should be written, and file position of lower layers
 524 adjusted for data read from below but not actually consumed.
 525 (Should perhaps C<Unread()> such data to the lower layer.)
 526
 527 Returns 0 on success, -1 on failure.
 528
 529 =item  IV               (*Fill)(pTHX_ PerlIO *f);
 530
 531 The buffer for this layer should be filled (for read) from layer
 532 below.  When you "subclass" PerlIOBuf layer, you want to use its
 533 I<_read> method and to supply your own fill method, which fills the
 534 PerlIOBuf's buffer.
 535
 536 Returns 0 on success, -1 on failure.
 537
 538 =item  IV               (*Eof)(pTHX_ PerlIO *f);
 539
 540 Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
 541
 542 Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
 543
 544 =item  IV               (*Error)(pTHX_ PerlIO *f);
 545
 546 Return error indicator. C<PerlIOBase_error()> is normally sufficient.
 547
 548 Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
 549 0 otherwise.
 550
 551 =item  void             (*Clearerr)(pTHX_ PerlIO *f);
 552
 553 Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
 554 to set the C<PERLIO_F_XXXXX> flags, which may suffice.
 555
 556 =item  void             (*Setlinebuf)(pTHX_ PerlIO *f);
 557
 558 Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
 559 PERLIO_F_LINEBUF flag and is normally sufficient.
 560
 561 =item  STDCHAR *        (*Get_base)(pTHX_ PerlIO *f);
 562
 563 Allocate (if not already done so) the read buffer for this layer and
 564 return pointer to it. Return NULL on failure.
 565
 566 =item  Size_t           (*Get_bufsiz)(pTHX_ PerlIO *f);
 567
 568 Return the number of bytes that last C<Fill()> put in the buffer.
 569
 570 =item  STDCHAR *        (*Get_ptr)(pTHX_ PerlIO *f);
 571
 572 Return the current read pointer relative to this layer's buffer.
 573
 574 =item  SSize_t  (*Get_cnt)(pTHX_ PerlIO *f);
 575
 576 Return the number of bytes left to be read in the current buffer.
 577
 578 =item  void             (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt);
 579
 580 Adjust the read pointer and count of bytes to match C<ptr> and/or C<cnt>.
 581 The application (or layer above) must ensure they are consistent.
 582 (Checking is allowed by the paranoid.)
 583
 584 =back
 585
 586
 587 =head2 Core Layers
 588
 589 The file C<perlio.c> provides the following layers:
 590
 591 =over 4
 592
 593 =item "unix"
 594
 595 A basic non-buffered layer which calls Unix/POSIX C<read()>, C<write()>,
 596 C<lseek()>, C<close()>. No buffering. Even on platforms that distinguish
 597 between O_TEXT and O_BINARY this layer is always O_BINARY.
 598
 599 =item "perlio"
 600
 601 A very complete generic buffering layer which provides the whole of
 602 PerlIO API. It is also intended to be used as a "base class" for other
 603 layers. (For example its C<Read()> method is implemented in terms of
 604 the C<Get_cnt()>/C<Get_ptr()>/C<Set_ptrcnt()> methods).
 605
 606 "perlio" over "unix" provides a complete replacement for stdio as seen
 607 via PerlIO API. This is the default for USE_PERLIO when system's stdio
 608 does not permit perl's "fast gets" access, and which do not
 609 distinguish between C<O_TEXT> and C<O_BINARY>.
 610
 611 =item "stdio"
 612
 613 A layer which provides the PerlIO API via the layer scheme, but
 614 implements it by calling system's stdio. This is (currently) the default
 615 if system's stdio provides sufficient access to allow perl's "fast gets"
 616 access and which do not distinguish between C<O_TEXT> and C<O_BINARY>.
 617
 618 =item "crlf"
 619
 620 A layer derived using "perlio" as a base class. It provides Win32-like
 621 "\n" to CR,LF translation. Can either be applied above "perlio" or serve
 622 as the buffer layer itself. "crlf" over "unix" is the default if system
 623 distinguishes between C<O_TEXT> and C<O_BINARY> opens. (At some point
 624 "unix" will be replaced by a "native" Win32 IO layer on that platform,
 625 as Win32's read/write layer has various drawbacks.) The "crlf" layer is
 626 a reasonable model for a layer which transforms data in some way.
 627
 628 =item "mmap"
 629
 630 If Configure detects C<mmap()> functions this layer is provided (with
 631 "perlio" as a "base") which does "read" operations by mmap()ing the
 632 file. Performance improvement is marginal on modern systems, so it is
 633 mainly there as a proof of concept. It is likely to be unbundled from
 634 the core at some point. The "mmap" layer is a reasonable model for a
 635 minimalist "derived" layer.
 636
 637 =item "pending"
 638
 639 An "internal" derivative of "perlio" which can be used to provide
 640 Unread() function for layers which have no buffer or cannot be
 641 bothered.  (Basically this layer's C<Fill()> pops itself off the stack
 642 and so resumes reading from layer below.)
 643
 644 =item "raw"
 645
 646 A dummy layer which never exists on the layer stack. Instead when
 647 "pushed" it actually pops the stack(!), removing itself, and any other
 648 layers until it reaches a layer with the class C<PERLIO_K_RAW> bit set.
 649
 650 =item "utf8"
 651
 652 Another dummy layer. When pushed it pops itself and sets the
 653 C<PERLIO_F_UTF8> flag on the layer which was (and now is once more)
 654 the top of the stack.
 655
 656 =back
 657
 658 In addition F<perlio.c> also provides a number of C<PerlIOBase_xxxx()>
 659 functions which are intended to be used in the table slots of classes
 660 which do not need to do anything special for a particular method.
 661
 662 =head2 Extension Layers
 663
 664 Layers can made available by extension modules. When an unknown layer
 665 is encountered the PerlIO code will perform the equivalent of :
 666
 667    use PerlIO 'layer';
 668
 669 Where I<layer> is the unknown layer. F<PerlIO.pm> will then attempt to:
 670
 671    require PerlIO::layer;
 672
 673 If after that process the layer is still not defined then the C<open>
 674 will fail.
 675
 676 The following extension layers are bundled with perl:
 677
 678 =over 4
 679
 680 =item ":encoding"
 681
 682    use Encoding;
 683
 684 makes this layer available, although F<PerlIO.pm> "knows" where to
 685 find it.  It is an example of a layer which takes an argument as it is
 686 called thus:
 687
 688    open($fh,"<:encoding(iso-8859-7)",$pathname)
 689
 690 =item ":Scalar"
 691
 692 Provides support for
 693
 694    open($fh,"...",\$scalar)
 695
 696 When a handle is so opened, then reads get bytes from the string value
 697 of I<$scalar>, and writes change the value. In both cases the position
 698 in I<$scalar> starts as zero but can be altered via C<seek>, and
 699 determined via C<tell>.
 700
 701 =item ":Object" or ":Perl"
 702
 703 May be provided to allow layers to be implemented as perl code -
 704 implementation is being investigated.
 705
 706 =back
 707
 708 =head1 TODO
 709
 710 Things that need to be done to improve this document.
 711
 712 =over
 713
 714 =item *
 715
 716 Explain how to make a valid fh without going through open()(i.e. apply
 717 a layer). For example if the file is not opened through perl, but we
 718 want to get back a fh, like it was opened by Perl.
 719
 720 How PerlIO_apply_layera fits in, where its docs, was it made public?
 721
 722 Currently the example could be something like this:
 723
 724   PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
 725   {
 726       char *mode; /* "w", "r", etc */
 727       const char *layers = ":APR"; /* the layer name */
 728       PerlIO *f = PerlIO_allocate(aTHX);
 729       if (!f) {
 730           return NULL;
 731       }
 732
 733       PerlIO_apply_layers(aTHX_ f, mode, layers);
 734
 735       if (f) {
 736           PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR);
 737           /* fill in the st struct, as in _open() */
 738           st->file = file;
 739           PerlIOBase(f)->flags |= PERLIO_F_OPEN;
 740
 741           return f;
 742       }
 743       return NULL;
 744   }
 745
 746 =item *
 747
 748 fix/add the documentation in places marked as XXX.
 749
 750 =item *
 751
 752 The handling of errors by the layer is not specified. e.g. when $!
 753 should be set explicitly, when the error handling should be just
 754 delegated to the top layer.
 755
 756 Probably give some hints on using SETERRNO() or pointers to where they
 757 can be found.
 758
 759 =item *
 760
 761 I think it would help to give some concrete examples to make it easier
 762 to understand the API. Of course I agree that the API has to be
 763 concise, but since there is no second document that is more of a
 764 guide, I think that it'd make it easier to start with the doc which is
 765 an API, but has examples in it in places where things are unclear, to
 766 a person who is not a PerlIO guru (yet).
 767
 768 =back
 769
 770 =cut
 771
 772
 773