X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=a560d970cb639b94e9ac740227338fcbbc1b5157;hb=6fa4d285bff5644bebb95aff09143322042282cc;hp=eb6433a97a232f52d3b70cbe7ab54d02f309c7d3;hpb=eae154c7dcbb63935731f10277d6aa4e40e86a6c;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perliol.pod b/pod/perliol.pod index eb6433a..a560d97 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -22,17 +22,17 @@ 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 as a stack of layers. +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. -Terms I and I are used to refer to the relative -positioning of the stack layers. +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 @@ -44,11 +44,17 @@ 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. 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, +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 @@ -139,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, @@ -240,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: @@ -480,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, @@ -488,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 @@ -553,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); @@ -727,10 +737,46 @@ 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: +look at the existing PerlIO layer implementations, which include: =over