X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperliol.pod;h=e51f309106ce17e911be665cf7d3d836319ad2d8;hb=ba370e9b8a212c313d985163053c7ed938fcae22;hp=34a5fb2b4d231de972551d2f0cef642ce9add08d;hpb=3039a93d20f525d68a979d28a46c6bc76a0d463e;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perliol.pod b/pod/perliol.pod index 34a5fb2..e51f309 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -11,27 +11,32 @@ perliol - C API for Perl's implementation of IO in Layers. =head1 DESCRIPTION -This document describes the behaviour and implementation of the PerlIO abstraction -described in L when C is defined (and C is not). +This document describes the behavior and implementation of the PerlIO +abstraction described in L when C is defined (and +C is not). =head2 History and Background -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 extensions -switched to using it, so the API is mostly fixed to maintain (source) compatibility. +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 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 and -platform neutral manner. It is also a trial of an "Object Oriented C, with vtables" -approach which may be applied to perl6. +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 Layers vs Disciplines -Initial discussion of the ability to modify IO streams behaviour used the term -"discipline" for the entities which were added. This came (I believe) from the use -of the term in "sfio", which in turn borowed 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. +Initial discussion of the ability to modify IO streams behaviour used +the term "discipline" for the entities which were added. This came (I +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. =head2 Data Structures @@ -48,86 +53,105 @@ The basic data structure is a PerlIOl: IV flags; /* Various flags for state */ }; -A PerlIOl * is a pointer to to the struct, and the I level PerlIO * -is a pointer to a PerlIOl * - i.e. a pointer to a pointer to the struct. -This allows the application level PerlIO * to remain constant while the actual -PerlIOl * underneath changes. (Compare perl's SV * which remains constant -while its sv_any 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 PerlIO *, -a &(perlio->next) "is" a PerlIO *, and so to some degree at least -one layer can use the "standard" API on the next layer down. +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 +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 =head2 Functions and Attributes -The functions and attributes are accessed via the "tab" (for table) member of -PerlIOl. The functions (methods of the layer "class") are fixed, and are defined by the -PerlIO_funcs type. They are broadly the same as the public PerlIO_xxxxx functions: +The functions and attributes are accessed via the "tab" (for table) +member of C. The functions (methods of the layer "class") are +fixed, and are defined by the C type. They are broadly the +same as the public C functions: + + struct _PerlIO_funcs + { + char * name; + Size_t size; + IV kind; + IV (*Pushed)(PerlIO *f,const char *mode,SV *arg); + IV (*Popped)(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); + /* 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); + /* 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); + /* 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); + }; + + + +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 +layer), then follow the functions which fall into four basic groups: - struct _PerlIO_funcs - { - char * name; - Size_t size; - IV kind; - IV (*Fileno)(PerlIO *f); - PerlIO * (*Fdopen)(PerlIO_funcs *tab, int fd, const char *mode); - PerlIO * (*Open)(PerlIO_funcs *tab, const char *path, const char *mode); - int (*Reopen)(const char *path, const char *mode, PerlIO *f); - IV (*Pushed)(PerlIO *f,const char *mode,const char *arg,STRLEN len); - IV (*Popped)(PerlIO *f); - /* 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); - /* 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); - /* 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); - }; +=over 4 -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 layer), then follow the functions which fall into -four basic groups: +=item 1. -=over 4 +Opening and setup functions + +=item 2. -=item 1. Opening and setup functions +Basic IO operations -=item 2. Basic IO operations +=item 3. -=item 3. Stdio class buffering options. +Stdio class buffering options. -=item 4. Functions to support Perl's traditional "fast" access to the buffer. +=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 +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 @@ -165,23 +189,23 @@ as a pointer to a PerlIOl. The above attempts to show how the layer scheme works in a simple case. -The application's PerlIO * points to an entry in the table(s) 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. +The application's C points to an entry in the table(s) +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. -The above is roughly equivalent to a "stdio" buffered stream, but with much more -flexibility: +The above is roughly equivalent to a "stdio" buffered stream, but with +much more flexibility: =over 4 =item * -If Unix level read/write/lseek is not appropriate for (say) sockets then -the "unix" layer can be replaced (at open time or even dynamically) with a -"socket" layer. +If Unix level C/C/C is not appropriate for (say) +sockets then the "unix" layer can be replaced (at open time or even +dynamically) with a "socket" layer. =item * @@ -193,11 +217,11 @@ 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 perkl5.70+ - we needed a mechanism -to allow data to be translated bewteen 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. +This was the driving need for including the scheme in perl 5.7.0+ - we +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 * @@ -208,11 +232,11 @@ on any platform, not just those that normally do such things. =head2 Per-instance flag bits -The generic flag bits are a hybrid of O_XXXXX style flags deduced from -the mode string passed to PerlIO_open() and state bits for typical buffer +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. -=over4 +=over 4 =item PERLIO_F_EOF @@ -228,7 +252,7 @@ Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick). =item PERLIO_F_ERROR -An error has occurred (for PerlIO_error()) +An error has occurred (for C) =item PERLIO_F_TRUNCATE @@ -240,10 +264,11 @@ All writes should be appends. =item PERLIO_F_CRLF -Layer is performing Win32-like "\n" => CR,LF for output and CR,LF => "\n" for -input. Normally the provided "crlf" layer is only layer than need bother about -this. PerlIO_binmode() will mess with this flag rather than add/remove layers -if the PERLIO_K_CANCRLF bit is set for the layers class. +Layer is performing Win32-like "\n" mapped to CR,LF for output and CR,LF +mapped to "\n" for input. Normally the provided "crlf" layer is the only +layer that need bother about this. C will mess with this +flag rather than add/remove layers if the C bit is set +for the layers class. =item PERLIO_F_UTF8 @@ -268,12 +293,13 @@ layer below. =item PERLIO_F_LINEBUF -Layer is line buffered. Write data should be passed to next layer down whenever a -"\n" is seen. Any data beyond the "\n" should then be processed. +Layer is line buffered. Write data should be passed to next layer down +whenever a "\n" is seen. Any data beyond the "\n" should then be +processed. =item PERLIO_F_TEMP -File has been unlink()ed, or should be deleted on close(). +File has been Ced, or should be deleted on C. =item PERLIO_F_OPEN @@ -281,13 +307,13 @@ Handle is open. =item PERLIO_F_FASTGETS -This instance of this layer supports the "fast gets" interface. -Normally set based on PERLIO_K_FASTGETS for the class and by the +This instance of this layer supports the "fast C" interface. +Normally set based on C for the class and by the 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 a layer which does not support the interface. -(Perls sv_gets() does not expect the stream's fast gets behaviour +(Perl's C does not expect the streams fast C behaviour to change during one "get".) =back @@ -296,54 +322,99 @@ to change during one "get".) =over 4 -=item IV (*Fileno)(PerlIO *f); - -Returns the Unix/Posix numeric file decriptor for the handle. -Normally PerlIOBase_fileno() (which just asks next layer down) will suffice for this. - -=item PerlIO * (*Fdopen)(PerlIO_funcs *tab, int fd, const char *mode); - -Should (perhaps indirectly) call PerlIO_allocate() to allocate a slot -in the table and associate it with the given numeric file descriptor, -which will be open in an manner compatible with the supplied mode string. - -=item PerlIO * (*Open)(PerlIO_funcs *tab, const char *path, const char *mode); - -Should attempt to open the given path and if that succeeds then (perhaps indirectly) -call PerlIO_allocate() to allocate a slot in the table and associate it with the -layers information for the opened file. +=item IV (*Pushed)(PerlIO *f,const char *mode, SV *arg); -=item int (*Reopen)(const char *path, const char *mode, PerlIO *f); +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). -Re-open the supplied PerlIO * to connect it to C in C. Returns as success flag. -Perl does not use this and L marks it as subject to change. - -=item IV (*Pushed)(PerlIO *f,const char *mode,const char *arg,STRLEN len); +=item IV (*Popped)(PerlIO *f); -Called when the layer is pushed onto the stack. The C argument may be NULL if this -occurs post-open. The C and C will be present if an argument string was -passed. In most cases this should call PerlIOBase_pushed() to convert C into -the appropriate PERLIO_F_XXXXX flags in addition to any actions the layer itself takes. +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 * (*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, + const char *mode, + int fd, int imode, int perm, + 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. + +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.) + +If I is not C then this is a C. Perl itself does not use +this (yet?) and semantics are a little vague. + +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 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. + +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. + +=item SV * (*Getarg)(PerlIO *f); + +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". -=item IV (*Popped)(PerlIO *f); +=item IV (*Fileno)(PerlIO *f); -Called when the layer is popped from the stack. A layer will normally be popped after -Close() is called. But a layer can be popped without being closed if the program -is dynamically managing layers on the stream. In such cases Popped() should free -any resources (buffers, translation tables, ...) not held directly in the layer's -struct. +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); Basic read operation. Returns actual bytes read, or -1 on an error. Typically will call Fill and manipulate pointers (possibly via the API). -PerlIOBuf_read() may be suitable for derived classes which provide "fast gets" methods. +C may be suitable for derived classes which provide +"fast gets" methods. =item SSize_t (*Unread)(PerlIO *f, const void *vbuf, Size_t count); -A superset of stdio's ungetc(). Should arrange for future reads to see the bytes in C. -If there is no obviously better implementation then PerlIOBase_unread() provides -the function by pushing a "fake" "pending" layer above the calling layer. +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); @@ -351,25 +422,27 @@ Basic write operation. Returns bytes written or -1 on an error. =item IV (*Seek)(PerlIO *f, Off_t offset, int whence); -Position the file pointer. Should normally call its own Flush method and -then the Seek 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); -Return the file pointer. May be based on layers cached concept of position to -avoid overhead. +Return the file pointer. May be based on layers cached concept of +position to avoid overhead. =item IV (*Close)(PerlIO *f); -Close the stream. Should normally call PerlIOBase_close() to flush itself -and Close layers below and then deallocate any data structures (buffers, translation -tables, ...) not held directly in the data structure. +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); -Should make streams state consistent with layers below. That is any -buffered write data should be written, and file position of lower layer +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 from below but not actually consumed. +(Should perhaps C such data to the lower layer.) =item IV (*Fill)(PerlIO *f); @@ -377,20 +450,21 @@ The buffer for this layer should be filled (for read) from layer below. =item IV (*Eof)(PerlIO *f); -Return end-of-file indicator. PerlIOBase_eof() is normally sufficient. +Return end-of-file indicator. C is normally sufficient. =item IV (*Error)(PerlIO *f); -Return error indicator. PerlIOBase_error() is normally sufficient. +Return error indicator. C is normally sufficient. =item void (*Clearerr)(PerlIO *f); -Clear end-of-file and error indicators. Should call PerlIOBase_clearerr() -to set the PERLIO_F_XXXXX flags, which may suffice. +Clear end-of-file and error indicators. Should call C +to set the C flags, which may suffice. =item void (*Setlinebuf)(PerlIO *f); -Mark the stream as line buffered. +Mark the stream as line buffered. C sets the +PERLIO_F_LINEBUF flag and is normally sufficient. =item STDCHAR * (*Get_base)(PerlIO *f); @@ -399,7 +473,7 @@ return pointer to it. =item Size_t (*Get_bufsiz)(PerlIO *f); -Return the number of bytes that last Fill() put in the buffer. +Return the number of bytes that last C put in the buffer. =item STDCHAR * (*Get_ptr)(PerlIO *f); @@ -426,86 +500,115 @@ The file C provides the following layers: =item "unix" -A basic non-buffered layer which calls Unix/POSIX read(), write(), lseek(), close(). -No buffering. Even on platforms that distinguish between O_TEXT and O_BINARY -this layer is always O_BINARY. +A basic non-buffered layer which calls Unix/POSIX C, C, +C, C. No buffering. Even on platforms that distinguish +between O_TEXT and O_BINARY this layer is always O_BINARY. =item "perlio" -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 Read() method is implemented in terms of the Get_cnt()/Get_ptr()/Set_ptrcnt() -methods). +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). -"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 O_TEXT and O_BINARY. +"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. =item "stdio" -A layer which provides the PerlIO API via the layer scheme, but implements it by calling -system's stdio. This is (currently) the default if system's stdio provides sufficient -access to allow perl's "fast gets" access and which do not distinguish between O_TEXT and -O_BINARY. +A layer which provides the PerlIO API via the layer scheme, but +implements it by calling system's stdio. This is (currently) the default +if system's stdio provides sufficient access to allow perl's "fast gets" +access and which do not distinguish between C and C. =item "crlf" -A layer derived using "perlio" as a base class. It provides Win32-like "\n" to CR,LF -translation. Can either be applied above "perlio" or serve as the buffer layer itself. -"crlf" over "unix" is the default if system distinguishes between O_TEXT and O_BINARY -opens. (At some point "unix" will be replaced by a "native" Win32 IO layer on that -platform, as Win32's read/write layer has various drawbacks.) -The "crlf" layer is a reasonable model for a layer which transforms data in some way. +A layer derived using "perlio" as a base class. It provides Win32-like +"\n" to CR,LF translation. Can either be applied above "perlio" or serve +as the buffer layer itself. "crlf" over "unix" is the default if system +distinguishes between C and C opens. (At some point +"unix" will be replaced by a "native" Win32 IO layer on that platform, +as Win32's read/write layer has various drawbacks.) The "crlf" layer is +a reasonable model for a layer which transforms data in some way. =item "mmap" -If Configure detects C functions this layer is provided (with "perlio" as a -"base") which does "read" operations by mmap()ing the file. Performance improvement -is marginal on modern systems, so it is mainly there as a proof of concept. -It is likely to be unbundled from the core at some point. -The "mmap" layer is a reasonable model for a minimalist "derived" layer. +If Configure detects C functions this layer is provided (with +"perlio" as a "base") which does "read" operations by mmap()ing the +file. Performance improvement is marginal on modern systems, so it is +mainly there as a proof of concept. It is likely to be unbundled from +the core at some point. The "mmap" layer is a reasonable model for a +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 Fill() pops itself off the stack and so resumes reading -from layer below.) +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.) =item "raw" -A dummy layer which never exists on the layer stack. Instead when "pushed" it -actually pops the stack!, removing itself, and any other layers until it reaches -a layer with the class PERLIO_K_RAW bit set. +A dummy layer which never exists on the layer stack. Instead when +"pushed" it actually pops the stack(!), removing itself, and any other +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 PERLIO_F_UTF8 flag -on the layer which was (and now is once more) the top of the stack. +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. =back -In addition C also provides a number of PerlIOBase_xxxx() functions -which are intended to be used in the table slots of classes which do not need -to do anything special for a particular method. +In addition F also provides a number of C +functions which are intended to be used in the table slots of classes +which do not need to do anything special for a particular method. =head2 Extension Layers -Layers can made available by extension modules. +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 : + + require PerlIO::layer; + +If after that process the layer is still not defined then the C will fail. + +The following extension layers are bundled with perl: =over 4 -=item "encoding" +=item ":encoding" use Encoding; -makes this layer available. It is an example of a layer which takes an argument. -as it is called as: +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) -=back +=item ":Scalar" + +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. + +=item ":Object" or ":Perl" + +May be provided to allow layers to be implemented as perl code - implementation +is being investigated. + +=back =cut