X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=9abc72ec59ada77cd324b2f509366ece06d5b8e8;hb=c23d1eb0e18a49361001d26c686323d50b0c6d21;hp=81cbab17e7c3eda203b37da127cb52c79e35818f;hpb=15af043884e0520355045b5d53efce3cdf6f3094;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perliol.pod b/pod/perliol.pod index 81cbab1..9abc72e 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -87,10 +87,11 @@ same as the public C functions: struct _PerlIO_funcs { + Size_t fsize; char * name; Size_t size; IV kind; - IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg); + 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, @@ -124,9 +125,9 @@ same as the public C functions: void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SSize_t cnt); }; -The first few members of the struct give a "name" for the layer, the -size to C for the per-instance data, and some flags which are -attributes of the class as whole (such as whether it is a buffering +The first few members of the struct give a function table size for +compatibility check "name" for the layer, the size to C for the per-instance data, +and some flags which are attributes of the class as whole (such as whether it is a buffering layer), then follow the functions which fall into four basic groups: =over 4 @@ -323,6 +324,14 @@ to change during one "get".) =over 4 +=item fsize + + Size_t fsize; + +Size of the function table. This is compared against the value PerlIO +code "knows" as a compatibility check. Future versions I be able +to tolerate layers compiled against an old version of the headers. + =item name char * name; @@ -343,6 +352,14 @@ The size of the per-instance data structure, e.g.: sizeof(PerlIOAPR) +If this field is zero then C does not malloc anything +and assumes layer's Pushed function will do any required layer stack +manipulation - used to avoid malloc/free overhead for dummy layers. +If the field is non-zero it must be at least the size of C, +C will allocate memory for the layer's data structures +and link new layer onto the stream's stack. (If the layer's Pushed +method returns an error indication the layer is popped again.) + =item kind IV kind; @@ -403,7 +420,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 @@ -437,10 +457,10 @@ special C calls; the C<'#'> prefix means that this is C and that I and I should be passed to C; C<'r'> means Bead, C<'w'> means Brite and C<'a'> means Bppend. The C<'+'> suffix means that both reading and -writing/appending are permitted. The C<'b'> suffix means file should -be binary, and C<'t'> means it is text. (Binary/Text should be ignored -by almost all layers and binary IO done, with PerlIO. The C<:crlf> -layer should be pushed to handle the distinction.) +writing/appending are permitted. The C<'b'> suffix means file should +be binary, and C<'t'> means it is text. (Almost all layers should do +the IO in binary mode, and ignore the b/t bits. The C<:crlf> layer +should be pushed to handle the distinction.) If I is not C then this is a C. Perl itself does not use this (yet?) and semantics are a little vague. @@ -461,6 +481,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 @@ -492,18 +516,19 @@ Returns the Unix/Posix numeric file descriptor for the handle. Normally C (which just asks next layer down) will suffice for this. -Returns -1 if the layer cannot provide such a file descriptor, or in -the case of the error. - -XXX: two possible results end up in -1, one is an error the other is -not. +Returns -1 on error, which is considered to include the case where the +layer cannot provide such a file descriptor. =item Dup PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags); -XXX: not documented +XXX: Needs more docs. + +Used as part of the "clone" process when a thread is spawned (in which +case param will be non-NULL) and when a stream is being duplicated via +'&' in the C. Similar to C, returns PerlIO* on success, C on failure. @@ -657,6 +682,68 @@ The application (or layer above) must ensure they are consistent. =back +=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 + +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 @@ -762,27 +849,31 @@ makes this layer available, although F "knows" where to find it. It is an example of a layer which takes an argument as it is called thus: - open($fh,"<:encoding(iso-8859-7)",$pathname) + open( $fh, "<:encoding(iso-8859-7)", $pathname ); -=item ":Scalar" +=item ":scalar" -Provides support for +Provides support for reading data from and writing data to a scalar. - open($fh,"...",\$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 MIME::QuotedPrint; - open(my $fh, ">Via(MIME::QuotedPrint)", "qp"); + use PerlIO::via::StripHTML; + open( my $fh, "<:via(StripHTML)", "index.html" ); -See L for details. +See L for details. =back @@ -849,6 +940,3 @@ a person who is not a PerlIO guru (yet). =back =cut - - -