From: Jarkko Hietaniemi Date: Sun, 21 Sep 2003 08:13:58 +0000 (+0000) Subject: More PerlIO documentation. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cc83745da206d409d7227df077f422fd9ecbe680;p=p5sagit%2Fp5-mst-13.2.git More PerlIO documentation. p4raw-id: //depot/perl@21293 --- diff --git a/lib/PerlIO.pm b/lib/PerlIO.pm index 5777679..9d1fa27 100644 --- a/lib/PerlIO.pm +++ b/lib/PerlIO.pm @@ -234,7 +234,8 @@ The following returns the B of the PerlIO layers on a filehandle. The layers are returned in the order an open() or binmode() call would use them. Note that the "default stack" depends on the operating -system and on the perl version. +system and on the Perl version, and both the compile-time and +runtime configurations of Perl. The following table summarizes the default layers on UNIX-like and DOS-like platforms and depending on the setting of the C<$ENV{PERLIO}>: diff --git a/pod/perliol.pod b/pod/perliol.pod index 9abc72e..8a41917 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -24,6 +24,51 @@ The aim of the implementation is to provide the PerlIO API in a flexible and platform neutral manner. It is also a trial of an "Object Oriented C, with vtables" approach which may be applied to perl6. +=head2 Basic Structure + +PerlIO is as a stack of layers. + +The low levels of the stack work with the low-level operating system +calls (file descriptors in C) getting bytes in and out, the higher +layers of the stack buffer, filter, and otherwise manipulate the I/O. +Terms I and I are used to refer to the relative +positioning of the stack layers. + +A layer contains a "vtable", the table of I/O operations (at C level +a table of function pointers), and status flags. The functions in the +vtable implement operations like "open", "read", and "write". + +When I/O, for example "read", is requested, the request goes from Perl +first down the stack using "read" functions of each layer, then at the +bottom the input is requested from the operating system services, then +the result is returned up the stack, finally being interpreted as Perl +data. + +When you do an open() and specify extra PerlIO layers to be deployed, +the layers you specify are "pushed" on top of the already existing +default stack. What exact layers are in this default stack depends on +a lot of things: your operating system, Perl version, Perl compile +time configuration, and Perl runtime configuration. See L, +L, and L for more information. + +binmode() operates similarly to open(): by default the specified +layers are pushed on top of the existing stack. + +However, note that even as the specified layers are "pushed on top" +for open() and binmode(), this doesn't mean that the effects are +limited to the "top": PerlIO layers can be very 'active' and inspect +and affect layers also deeper in the stack. As an example there +is a layer called "raw" which repeatedly "pops" layers until +it reaches the first layer that has declared itself capable of +handling binary data. The "pushed" layers are processed in left-to-right +order. + +sysopen() operates (unsurprisingly) at a lower level in the stack than +open(). For example in UNIX or UNIX-like systems sysopen() operates +directly at the level of file descriptors: in the terms of PerlIO +layers, it uses only the "unix" layer, which is a rather thin wrapper +on top of the UNIX file descriptors. + =head2 Layers vs Disciplines Initial discussion of the ability to modify IO streams behaviour used