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