X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=1c346e0965ec1dcb426ee23fc7a32ad5fe309411;hb=666f95b95a2f6347f7b7bbc8951144df2db05479;hp=68f581428c38f41fa8fda4dd5b2026188b1dbf83;hpb=b76cc8ba45957a82b545cf2a7b818233e6c0d507;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perliol.pod b/pod/perliol.pod index 68f5814..1c346e0 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -1,4 +1,3 @@ - =head1 NAME perliol - C API for Perl's implementation of IO in Layers. @@ -8,7 +7,6 @@ perliol - C API for Perl's implementation of IO in Layers. /* Defining a layer ... */ #include - =head1 DESCRIPTION This document describes the behavior and implementation of the PerlIO @@ -19,7 +17,7 @@ C is not). The PerlIO abstraction was introduced in perl5.003_02 but languished as just an abstraction until perl5.7.0. However during that time a number -of perl extentions switched to using it, so the API is mostly fixed to +of perl extensions switched to using it, so the API is mostly fixed to maintain (source) compatibility. The aim of the implementation is to provide the PerlIO API in a flexible @@ -34,9 +32,9 @@ believe) from the use of the term in "sfio", which in turn borrowed it from "line disciplines" on Unix terminals. However, this document (and the C code) uses the term "layer". -This is, I hope, a natural term given the implementation, and should avoid -connotations that are inherent in earlier uses of "discipline" for things -which are rather different. +This is, I hope, a natural term given the implementation, and should +avoid connotations that are inherent in earlier uses of "discipline" +for things which are rather different. =head2 Data Structures @@ -53,25 +51,30 @@ The basic data structure is a PerlIOl: IV flags; /* Various flags for state */ }; -A C is a pointer to to the struct, and the I level -C is a pointer to a C - i.e. a pointer to a pointer to -the struct. This allows the application level C to remain -constant while the actual C underneath changes. (Compare perl's -C which remains constant while its C field changes as the -scalar's type changes.) An IO stream is then in general represented as a -pointer to this linked-list of "layers". +A C is a pointer to the struct, and the I +level C is a pointer to a C - i.e. a pointer +to a pointer to the struct. This allows the application level C +to remain constant while the actual C underneath +changes. (Compare perl's C which remains constant while its +C field changes as the scalar's type changes.) An IO stream is +then in general represented as a pointer to this linked-list of +"layers". It should be noted that because of the double indirection in a C, -a C<< &(perlio-Enext) >> "is" a C, and so to some degree +a C<< &(perlio->next) >> "is" a C, and so to some degree at least one layer can use the "standard" API on the next layer down. A "layer" is composed of two parts: =over 4 -=item 1. The functions and attributes of the "layer class". +=item 1. + +The functions and attributes of the "layer class". -=item 2. The per-instance data for a particular handle. +=item 2. + +The per-instance data for a particular handle. =back @@ -87,40 +90,39 @@ same as the public C functions: char * name; Size_t size; IV kind; - IV (*Pushed)(PerlIO *f,const char *mode,SV *arg); - IV (*Popped)(PerlIO *f); + IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg); + IV (*Popped)(pTHX_ PerlIO *f); PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, AV *layers, IV n, const char *mode, int fd, int imode, int perm, PerlIO *old, int narg, SV **args); - SV * (*Getarg)(PerlIO *f); - IV (*Fileno)(PerlIO *f); + SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags) + IV (*Fileno)(pTHX_ PerlIO *f); + PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags) /* Unix-like functions - cf sfio line disciplines */ - SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count); - SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count); - SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); - IV (*Seek)(PerlIO *f, Off_t offset, int whence); - Off_t (*Tell)(PerlIO *f); - IV (*Close)(PerlIO *f); + SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); + SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); + SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count); + IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); + Off_t (*Tell)(pTHX_ PerlIO *f); + IV (*Close)(pTHX_ PerlIO *f); /* Stdio-like buffered IO functions */ - IV (*Flush)(PerlIO *f); - IV (*Fill)(PerlIO *f); - IV (*Eof)(PerlIO *f); - IV (*Error)(PerlIO *f); - void (*Clearerr)(PerlIO *f); - void (*Setlinebuf)(PerlIO *f); + IV (*Flush)(pTHX_ PerlIO *f); + IV (*Fill)(pTHX_ PerlIO *f); + IV (*Eof)(pTHX_ PerlIO *f); + IV (*Error)(pTHX_ PerlIO *f); + void (*Clearerr)(pTHX_ PerlIO *f); + void (*Setlinebuf)(pTHX_ PerlIO *f); /* Perl's snooping functions */ - STDCHAR * (*Get_base)(PerlIO *f); - Size_t (*Get_bufsiz)(PerlIO *f); - STDCHAR * (*Get_ptr)(PerlIO *f); - SSize_t (*Get_cnt)(PerlIO *f); - void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt); + STDCHAR * (*Get_base)(pTHX_ PerlIO *f); + Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); + STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); + SSize_t (*Get_cnt)(pTHX_ PerlIO *f); + 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 @@ -128,27 +130,36 @@ layer), then follow the functions which fall into four basic groups: =over 4 -=item 1. Opening and setup functions +=item 1. -=item 2. Basic IO operations +Opening and setup functions -=item 3. Stdio class buffering options. +=item 2. -=item 4. Functions to support Perl's traditional "fast" access to the buffer. +Basic IO operations + +=item 3. + +Stdio class buffering options. + +=item 4. + +Functions to support Perl's traditional "fast" access to the buffer. =back -A layer does not have to implement all the functions, but the whole table has -to be present. Unimplemented slots can be NULL (which will will result in an error -when called) or can be filled in with stubs to "inherit" behaviour from -a "base class". This "inheritance" is fixed for all instances of the layer, -but as the layer chooses which stubs to populate the table, limited -"multiple inheritance" is possible. +A layer does not have to implement all the functions, but the whole +table has to be present. Unimplemented slots can be NULL (which will +result in an error when called) or can be filled in with stubs to +"inherit" behaviour from a "base class". This "inheritance" is fixed +for all instances of the layer, but as the layer chooses which stubs +to populate the table, limited "multiple inheritance" is possible. =head2 Per-instance Data -The per-instance data are held in memory beyond the basic PerlIOl struct, -by making a PerlIOl the first member of the layer's struct thus: +The per-instance data are held in memory beyond the basic PerlIOl +struct, by making a PerlIOl the first member of the layer's struct +thus: typedef struct { @@ -161,8 +172,8 @@ by making a PerlIOl the first member of the layer's struct thus: IV oneword; /* Emergency buffer */ } PerlIOBuf; -In this way (as for perl's scalars) a pointer to a PerlIOBuf can be treated -as a pointer to a PerlIOl. +In this way (as for perl's scalars) a pointer to a PerlIOBuf can be +treated as a pointer to a PerlIOl. =head2 Layers in action. @@ -197,32 +208,33 @@ dynamically) with a "socket" layer. =item * -Different handles can have different buffering schemes. The "top" layer -could be the "mmap" layer if reading disk files was quicker using C -than C. An "unbuffered" stream can be implemented simply by -not having a buffer layer. +Different handles can have different buffering schemes. The "top" +layer could be the "mmap" layer if reading disk files was quicker +using C than C. An "unbuffered" stream can be implemented +simply by not having a buffer layer. =item * Extra layers can be inserted to process the data as it flows through. This was the driving need for including the scheme in perl 5.7.0+ - we -needed a mechanism to allow data to be translated bewteen perl's +needed a mechanism to allow data to be translated between perl's internal encoding (conceptually at least Unicode as UTF-8), and the "native" format used by the system. This is provided by the ":encoding(xxxx)" layer which typically sits above the buffering layer. =item * -A layer can be added that does "\n" to CRLF translation. This layer can be used -on any platform, not just those that normally do such things. +A layer can be added that does "\n" to CRLF translation. This layer +can be used on any platform, not just those that normally do such +things. =back =head2 Per-instance flag bits -The generic flag bits are a hybrid of C style flags deduced from -the mode string passed to C, and state bits for typical buffer -layers. +The generic flag bits are a hybrid of C style flags deduced +from the mode string passed to C, and state bits for +typical buffer layers. =over 4 @@ -240,7 +252,7 @@ Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick). =item PERLIO_F_ERROR -An error has occured (for C) +An error has occurred (for C). =item PERLIO_F_TRUNCATE @@ -297,10 +309,10 @@ Handle is open. This instance of this layer supports the "fast C" interface. Normally set based on C for the class and by the -existance of the function(s) in the table. However a class that +existence of the function(s) in the table. However a class that normally provides that interface may need to avoid it on a particular instance. The "pending" layer needs to do this when -it is pushed above an layer which does not support the interface. +it is pushed above a layer which does not support the interface. (Perl's C does not expect the streams fast C behaviour to change during one "get".) @@ -310,32 +322,89 @@ to change during one "get".) =over 4 -=item IV (*Pushed)(PerlIO *f,const char *mode, SV *arg); +=item name + + char * name; + +The name of the layer whose open() method Perl should invoke on +open(). For example if the layer is called APR, you will call: + + open $fh, ">:APR", ... + +and Perl knows that it has to invoke the PerlIOAPR_open() method +implemented by the APR layer. + +=item size + + Size_t size; + +The size of the per-instance data structure, e.g.: + + sizeof(PerlIOAPR) + +=item kind + + IV kind; + + XXX: explain all the available flags here + +=over 4 + +=item * PERLIO_K_BUFFERED -The only absoultely mandatory method. Called when the layer is pushed onto the stack. -The C argument may be NULL if this occurs post-open. The C will be non-C -if an argument string was passed. In most cases this should call -C to convert C into the appropriate -C flags in addition to any actions the layer itself takes. -If a layer is not expecting an argument it need neither save the one passed to it, nor -provide C (it could perhaps C that the argument was un-expected). +=item * PERLIO_K_CANCRLF -=item IV (*Popped)(PerlIO *f); +=item * PERLIO_K_FASTGETS -Called when the layer is popped from the stack. A layer will normally be -popped after C is called. But a layer can be popped without being -closed if the program is dynamically managing layers on the stream. In -such cases C should free any resources (buffers, translation -tables, ...) not held directly in the layer's 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. +=item * PERLIO_K_MULTIARG -=item PerlIO * (*Open)(...); +Used when the layer's open() accepts more arguments than usual. The +extra arguments should come not before the C argument. When this +flag is used it's up to the layer to validate the args. -The C method has lots of arguments because it combines the functions -of perl's C, C, perl's C, C and C. -The full prototype is as follows: +=item * PERLIO_K_RAW + +=back + +=item Pushed + + IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg); + +The only absolutely mandatory method. Called when the layer is pushed +onto the stack. The C argument may be NULL if this occurs +post-open. The C will be non-C if an argument string was +passed. In most cases this should call C to +convert C into the appropriate C flags in +addition to any actions the layer itself takes. If a layer is not +expecting an argument it need neither save the one passed to it, nor +provide C (it could perhaps C that the argument +was un-expected). + +Returns 0 on success. On failure returns -1 and should set errno. + +=item Popped + + IV (*Popped)(pTHX_ PerlIO *f); + +Called when the layer is popped from the stack. A layer will normally +be popped after C is called. But a layer can be popped +without being closed if the program is dynamically managing layers on +the stream. In such cases C should free any resources +(buffers, translation tables, ...) not held directly in the layer's +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. + +=item Open + + PerlIO * (*Open)(...); + +The C method has lots of arguments because it combines the +functions of perl's C, C, perl's C, +C and C. The full prototype is as +follows: PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, AV *layers, IV n, @@ -344,134 +413,225 @@ The full prototype is as follows: PerlIO *old, int narg, SV **args); -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 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 C) SV * -for the argument passed to the layer. +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 +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 +C) SV * for the argument passed to the layer. + +The I string is an "C-like" string which would match +the regular expression C. + +The C<'I'> prefix is used during creation of C..C via +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.) -The I string is an "C-like" string which would match the regular -expression C. +If I is not C then this is a C. Perl itself +does not use this (yet?) and semantics are a little vague. -The C<'I'> prefix is used during creation of C..C via 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 permited. 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.) +If I not negative then it is the numeric file descriptor I, +which will be open in a manner compatible with the supplied mode +string, the call is thus equivalent to C. In this case +I will be zero. -If I is not C then this is a C. Perl iteself does not use -this (yet?) and semantics are a little vague. +If I is greater than zero then it gives the number of arguments +passed to C, otherwise it will be 1 if for example +C was called. In simple cases SvPV_nolen(*args) is the +pathname to open. -If I not negative then it is the numeric file descriptor I, which will -be open in an manner compatible with the supplied mode string, the call is -thus equivalent to C. In this case I will be zero. +Having said all that translation-only layers do not need to provide +C at all, but rather leave the opening to a lower level layer +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 I is greater than zero then it gives the number of arguments passed -to C, otherwise it will be 1 if for example C was called. -In simple cases SvPV(*args) is the pathname to open. +Returns C on failure. -Having said all that translation-only layers do not need to provide C at all, -but rather leave the opening to a lower level layer and wait to be "pushed". -If a layer does provide C it should normaly call the C method -of next layer down (if any) and then push itself on top if that succeeds. +=item Getarg -=item SV * (*Getarg)(PerlIO *f); + SV * (*Getarg)(pTHX_ PerlIO *f, + CLONE_PARAMS *param, int flags); -Optional. If present should return an SV * representing the string argument -passed to the layer when it was pushed. e.g. ":encoding(ascii)" would -return an SvPV with value "ascii". +Optional. If present should return an SV * representing the string +argument passed to the layer when it was +pushed. e.g. ":encoding(ascii)" would return an SvPV with value +"ascii". (I and I arguments can be ignored in most +cases) -=item IV (*Fileno)(PerlIO *f); +=item Fileno -Returns the Unix/Posix numeric file decriptor for the handle. Normally + IV (*Fileno)(pTHX_ PerlIO *f); + +Returns the Unix/Posix numeric file descriptor for the handle. Normally C (which just asks next layer down) will suffice for this. -=item SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count); +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. + +=item Dup + + PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, + CLONE_PARAMS *param, int flags); + +XXX: not documented + +Similar to C, returns PerlIO* on success, C on failure. + +=item Read + + SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count); + +Basic read operation. -Basic read operation. Returns actual bytes read, or -1 on an error. -Typically will call Fill and manipulate pointers (possibly via the API). -C may be suitable for derived classes which provide -"fast gets" methods. +Typically will call C and manipulate pointers (possibly via the +API). C may be suitable for derived classes which +provide "fast gets" methods. -=item SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count); +Returns actual bytes read, or -1 on an error. + +=item Unread + + SSize_t (*Unread)(pTHX_ PerlIO *f, + const void *vbuf, Size_t count); A superset of stdio's C. Should arrange for future reads to see the bytes in C. If there is no obviously better implementation then C provides the function by pushing a "fake" "pending" layer above the calling layer. -=item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); +Returns the number of unread chars. + +=item Write + + SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count); + +Basic write operation. + +Returns bytes written or -1 on an error. -Basic write operation. Returns bytes written or -1 on an error. +=item Seek -=item IV (*Seek)(PerlIO *f, Off_t offset, int whence); + IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence); -Position the file pointer. Should normally call its own C method and -then the C method of next layer down. +Position the file pointer. Should normally call its own C +method and then the C method of next layer down. -=item Off_t (*Tell)(PerlIO *f); +Returns 0 on success, -1 on failure. + +=item Tell + + Off_t (*Tell)(pTHX_ PerlIO *f); Return the file pointer. May be based on layers cached concept of position to avoid overhead. -=item IV (*Close)(PerlIO *f); +Returns -1 on failure to get the file pointer. + +=item Close + + IV (*Close)(pTHX_ PerlIO *f); Close the stream. Should normally call C to flush itself and close layers below, and then deallocate any data structures (buffers, translation tables, ...) not held directly in the data structure. -=item IV (*Flush)(PerlIO *f); +Returns 0 on success, -1 on failure. + +=item Flush + + IV (*Flush)(pTHX_ PerlIO *f); Should make stream's state consistent with layers below. That is, any buffered write data should be written, and file position of lower layers -adjusted for data read fron below but not actually consumed. +adjusted for data read from below but not actually consumed. (Should perhaps C such data to the lower layer.) -=item IV (*Fill)(PerlIO *f); +Returns 0 on success, -1 on failure. -The buffer for this layer should be filled (for read) from layer below. +=item Fill -=item IV (*Eof)(PerlIO *f); + IV (*Fill)(pTHX_ PerlIO *f); + +The buffer for this layer should be filled (for read) from layer +below. When you "subclass" PerlIOBuf layer, you want to use its +I<_read> method and to supply your own fill method, which fills the +PerlIOBuf's buffer. + +Returns 0 on success, -1 on failure. + +=item Eof + + IV (*Eof)(pTHX_ PerlIO *f); Return end-of-file indicator. C is normally sufficient. -=item IV (*Error)(PerlIO *f); +Returns 0 on end-of-file, 1 if not end-of-file, -1 on error. + +=item Error + + IV (*Error)(pTHX_ PerlIO *f); Return error indicator. C is normally sufficient. -=item void (*Clearerr)(PerlIO *f); +Returns 1 if there is an error (usually when C is set, +0 otherwise. + +=item Clearerr + + void (*Clearerr)(pTHX_ PerlIO *f); Clear end-of-file and error indicators. Should call C to set the C flags, which may suffice. -=item void (*Setlinebuf)(PerlIO *f); +=item Setlinebuf + + void (*Setlinebuf)(pTHX_ PerlIO *f); Mark the stream as line buffered. C sets the PERLIO_F_LINEBUF flag and is normally sufficient. -=item STDCHAR * (*Get_base)(PerlIO *f); +=item Get_base + + STDCHAR * (*Get_base)(pTHX_ PerlIO *f); Allocate (if not already done so) the read buffer for this layer and -return pointer to it. +return pointer to it. Return NULL on failure. + +=item Get_bufsiz -=item Size_t (*Get_bufsiz)(PerlIO *f); + Size_t (*Get_bufsiz)(pTHX_ PerlIO *f); Return the number of bytes that last C put in the buffer. -=item STDCHAR * (*Get_ptr)(PerlIO *f); +=item Get_ptr + + STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f); Return the current read pointer relative to this layer's buffer. -=item SSize_t (*Get_cnt)(PerlIO *f); +=item Get_cnt + + SSize_t (*Get_cnt)(pTHX_ PerlIO *f); Return the number of bytes left to be read in the current buffer. -=item void (*Set_ptrcnt)(PerlIO *f,STDCHAR *ptr,SSize_t cnt); +=item Set_ptrcnt + + void (*Set_ptrcnt)(pTHX_ PerlIO *f, + STDCHAR *ptr, SSize_t cnt); Adjust the read pointer and count of bytes to match C and/or C. The application (or layer above) must ensure they are consistent. @@ -496,13 +656,13 @@ between O_TEXT and O_BINARY this layer is always O_BINARY. A very complete generic buffering layer which provides the whole of PerlIO API. It is also intended to be used as a "base class" for other -layers. (For example its C method is implemented in terms of the -C/C/C methods). +layers. (For example its C method is implemented in terms of +the C/C/C methods). "perlio" over "unix" provides a complete replacement for stdio as seen via PerlIO API. This is the default for USE_PERLIO when system's stdio -does not permit perl's "fast gets" access, and which do not distinguish -between C and C. +does not permit perl's "fast gets" access, and which do not +distinguish between C and C. =item "stdio" @@ -533,9 +693,9 @@ minimalist "derived" layer. =item "pending" An "internal" derivative of "perlio" which can be used to provide -Unread() function for layers which have no buffer or cannot be bothered. -(Basically this layer's C pops itself off the stack and so resumes -reading from layer below.) +Unread() function for layers which have no buffer or cannot be +bothered. (Basically this layer's C pops itself off the stack +and so resumes reading from layer below.) =item "raw" @@ -546,8 +706,8 @@ layers until it reaches a layer with the class C bit set. =item "utf8" Another dummy layer. When pushed it pops itself and sets the -C flag on the layer which was (and now is once more) the top -of the stack. +C flag on the layer which was (and now is once more) +the top of the stack. =back @@ -557,16 +717,17 @@ which do not need to do anything special for a particular method. =head2 Extension Layers -Layers can made available by extension modules. When an unknown layer is encountered -the PerlIO code will perform the equivalent of : +Layers can made available by extension modules. When an unknown layer +is encountered the PerlIO code will perform the equivalent of : use PerlIO 'layer'; -Where I is the unknown layer. F will then attempt to : +Where I is the unknown layer. F will then attempt to: require PerlIO::layer; -If after that process the layer is still not defined then the C will fail. +If after that process the layer is still not defined then the C +will fail. The following extension layers are bundled with perl: @@ -576,8 +737,9 @@ The following extension layers are bundled with perl: use Encoding; -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: +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) @@ -587,14 +749,77 @@ Provides support for open($fh,"...",\$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. +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 ":Object" or ":Perl" -May be provided to allow layers to be implemented as perl code - implementation -is being investigated. +May be provided to allow layers to be implemented as perl code - +implementation is being investigated. + +=back + +=head1 TODO + +Things that need to be done to improve this document. + +=over + +=item * + +Explain how to make a valid fh without going through open()(i.e. apply +a layer). For example if the file is not opened through perl, but we +want to get back a fh, like it was opened by Perl. + +How PerlIO_apply_layera fits in, where its docs, was it made public? + +Currently the example could be something like this: + + PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...) + { + char *mode; /* "w", "r", etc */ + const char *layers = ":APR"; /* the layer name */ + PerlIO *f = PerlIO_allocate(aTHX); + if (!f) { + return NULL; + } + + PerlIO_apply_layers(aTHX_ f, mode, layers); + + if (f) { + PerlIOAPR *st = PerlIOSelf(f, PerlIOAPR); + /* fill in the st struct, as in _open() */ + st->file = file; + PerlIOBase(f)->flags |= PERLIO_F_OPEN; + + return f; + } + return NULL; + } + +=item * + +fix/add the documentation in places marked as XXX. + +=item * + +The handling of errors by the layer is not specified. e.g. when $! +should be set explicitly, when the error handling should be just +delegated to the top layer. + +Probably give some hints on using SETERRNO() or pointers to where they +can be found. + +=item * + +I think it would help to give some concrete examples to make it easier +to understand the API. Of course I agree that the API has to be +concise, but since there is no second document that is more of a +guide, I think that it'd make it easier to start with the doc which is +an API, but has examples in it in places where things are unclear, to +a person who is not a PerlIO guru (yet). =back