X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/e934609f7db1163b003ba7314f8d52ebfc1e2f12..a452d459f5ff77fd7605dd9d2f58e9d44bc227cf:/pod/perliol.pod diff --git a/pod/perliol.pod b/pod/perliol.pod index 08ea7c6..a560d97 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -22,7 +22,58 @@ maintain (source) compatibility. 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. +C, with vtables" approach which may be applied to Perl 6. + +=head2 Basic Structure + +PerlIO is 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, +and return characters (or bytes) to Perl. 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. + +The requests do not necessarily go always all the way down to the +operating system: that's where PerlIO buffering comes into play. + +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. One way to see it is that "operating system is +on the left" and "Perl is on the right". + +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 @@ -94,7 +145,7 @@ same as the public C functions: IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab); IV (*Popped)(pTHX_ PerlIO *f); PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, - AV *layers, IV n, + PerlIO_list_t *layers, IV n, const char *mode, int fd, int imode, int perm, PerlIO *old, @@ -195,7 +246,7 @@ representing open (allocated) handles. For example the first three slots in the table correspond to C,C and C. The table in turn points to the current "top" layer for the handle - in this case an instance of the generic buffering layer "perlio". That layer in turn -points to the next layer down - in this case the lowlevel "unix" layer. +points to the next layer down - in this case the low-level "unix" layer. The above is roughly equivalent to a "stdio" buffered stream, but with much more flexibility: @@ -420,7 +471,10 @@ struct. It should also C any unconsumed data that has been read and buffered from the layer below back to that layer, so that it can be re-provided to what ever is now above. -Returns 0 on success and failure. +Returns 0 on success and failure. If C returns I then +I assumes that either the layer has popped itself, or the +layer is super special and needs to be retained for other reasons. +In most cases it should return I. =item Open @@ -432,7 +486,7 @@ C and C. The full prototype is as follows: PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, - AV *layers, IV n, + PerlIO_list_t *layers, IV n, const char *mode, int fd, int imode, int perm, PerlIO *old, @@ -440,7 +494,7 @@ follows: Open should (perhaps indirectly) call C to allocate a slot in the table and associate it with the layers information for -the opened file, by calling C. The I AV is an +the opened file, by calling C. The I is an array of all the layers destined for the C, and any arguments passed to them, I is the index into that array of the layer being called. The macro C will return a (possibly @@ -478,6 +532,10 @@ and wait to be "pushed". If a layer does provide C it should normally call the C method of next layer down (if any) and then push itself on top if that succeeds. +If C was performed and open has failed, it must +C itself, since if it's not, the layer won't be removed +and may cause bad problems. + Returns C on failure. =item Binmode @@ -501,6 +559,10 @@ pushed. e.g. ":encoding(ascii)" would return an SvPV with value "ascii". (I and I arguments can be ignored in most cases) +C uses C to retrieve the argument originally passed to +C, so you must implement this function if your layer has an +extra argument to C and will ever be Ced. + =item Fileno IV (*Fileno)(pTHX_ PerlIO *f); @@ -675,6 +737,110 @@ The application (or layer above) must ensure they are consistent. =back +=head2 Utilities + +To ask for the next layer down use PerlIONext(PerlIO *f). + +To check that a PerlIO* is valid use PerlIOValid(PerlIO *f). (All +this does is really just to check that the pointer is non-NULL and +that the pointer behind that is non-NULL.) + +PerlIOBase(PerlIO *f) returns the "Base" pointer, or in other words, +the C pointer. + +PerlIOSelf(PerlIO* f, type) return the PerlIOBase cast to a type. + +Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) either +calls the I from the functions of the layer I (just by +the name of the IO function, like "Read") with the I, or if +there is no such callback, calls the I version of the callback +with the same args, or if the f is invalid, set errno to EBADF and +return I. + +Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) either calls +the I of the functions of the layer I with the I, +or if there is no such callback, set errno to EINVAL. Or if the f is +invalid, set errno to EBADF and return I. + +Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) either calls +the I of the functions of the layer I with the I, +or if there is no such callback, calls the I version of the +callback with the same args, or if the f is invalid, set errno to +EBADF. + +Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) either calls the +I of the functions of the layer I with the I, or if +there is no such callback, set errno to EINVAL. Or if the f is +invalid, set errno to EBADF. + +=head2 Implementing PerlIO Layers + +If you find the implementation document unclear or not sufficient, +look at the existing PerlIO layer implementations, which include: + +=over + +=item * C implementations + +The F and F in the Perl core implement the +"unix", "perlio", "stdio", "crlf", "utf8", "byte", "raw", "pending" +layers, and also the "mmap" and "win32" layers if applicable. +(The "win32" is currently unfinished and unused, to see what is used +instead in Win32, see L .) + +PerlIO::encoding, PerlIO::scalar, PerlIO::via in the Perl core. + +PerlIO::gzip and APR::PerlIO (mod_perl 2.0) on CPAN. + +=item * Perl implementations + +PerlIO::via::QuotedPrint in the Perl core and PerlIO::via::* on CPAN. + +=back + +If you are creating a PerlIO layer, you may want to be lazy, in other +words, implement only the methods that interest you. The other methods +you can either replace with the "blank" methods + + PerlIOBase_noop_ok + PerlIOBase_noop_fail + +(which do nothing, and return zero and -1, respectively) or for +certain methods you may assume a default behaviour by using a NULL +method. The Open method looks for help in the 'parent' layer. +The following table summarizes the behaviour: + + method behaviour with NULL + + Clearerr PerlIOBase_clearerr + Close PerlIOBase_close + Dup PerlIOBase_dup + Eof PerlIOBase_eof + Error PerlIOBase_error + Fileno PerlIOBase_fileno + Fill FAILURE + Flush SUCCESS + Getarg SUCCESS + Get_base FAILURE + Get_bufsiz FAILURE + Get_cnt FAILURE + Get_ptr FAILURE + Open INHERITED + Popped SUCCESS + Pushed SUCCESS + Read PerlIOBase_read + Seek FAILURE + Set_cnt FAILURE + Set_ptrcnt FAILURE + Setlinebuf PerlIOBase_setlinebuf + Tell FAILURE + Unread PerlIOBase_unread + Write FAILURE + + FAILURE Set errno (to EINVAL in UNIXish, to LIB$_INVARG in VMS) and + return -1 (for numeric return values) or NULL (for pointers) + INHERITED Inherited from the layer below + SUCCESS Return 0 (for numeric return values) or a pointer =head2 Core Layers @@ -782,23 +948,27 @@ called thus: open( $fh, "<:encoding(iso-8859-7)", $pathname ); -=item ":Scalar" +=item ":scalar" Provides support for reading data from and writing data to a scalar. - open( $fh, ":Scalar", \$scalar ); + open( $fh, "+<:scalar", \$scalar ); When a handle is so opened, then reads get bytes from the string value of I<$scalar>, and writes change the value. In both cases the position in I<$scalar> starts as zero but can be altered via C, and determined via C. -=item ":Via" +Please note that this layer is implied when calling open() thus: + + open( $fh, "+<", \$scalar ); + +=item ":via" Provided to allow layers to be implemented as Perl code. For instance: use PerlIO::via::StripHTML; - open( my $fh, ">:Via(StripHTML)", "index.html" ); + open( my $fh, "<:via(StripHTML)", "index.html" ); See L for details.