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
IV flags; /* Various flags for state */
};
-A C<PerlIOl *> is a pointer to to the struct, and the I<application> level
+A C<PerlIOl *> is a pointer to the struct, and the I<application> level
C<PerlIO *> is a pointer to a C<PerlIOl *> - i.e. a pointer to a pointer to
the struct. This allows the application level C<PerlIO *> to remain
constant while the actual C<PerlIOl *> underneath changes. (Compare perl's
fixed, and are defined by the C<PerlIO_funcs> type. They are broadly the
same as the public C<PerlIO_xxxxx> functions:
- 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);
- };
+ 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<malloc> for the per-instance data, and some flags which are
=over 4
-=item 1. Opening and setup functions
+=item 1.
+
+Opening and setup functions
-=item 2. Basic IO operations
+=item 2.
-=item 3. Stdio class buffering options.
+Basic IO operations
-=item 4. Functions to support Perl's traditional "fast" access to the buffer.
+=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
+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
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 PERLIO_F_ERROR
-An error has occured (for C<PerlIO_error()>)
+An error has occurred (for C<PerlIO_error()>)
=item PERLIO_F_TRUNCATE
This instance of this layer supports the "fast C<gets>" interface.
Normally set based on C<PERLIO_K_FASTGETS> 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<sv_gets()> does not expect the streams fast C<gets> behaviour
to change during one "get".)
=over 4
-=item IV (*Fileno)(PerlIO *f);
-
-Returns the Unix/Posix numeric file decriptor for the handle. Normally
-C<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 C<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 C<PerlIO_allocate()> to allocate a slot in the table and
-associate it with the layers information for the opened file.
-
-=item int (*Reopen)(const char *path, const char *mode, PerlIO *f);
-
-Re-open the supplied C<PerlIO *> to connect it to C<path> in C<mode>.
-Returns as success flag. Perl does not use this and L<perlapio> marks it
-as subject to change.
+=item IV (*Pushed)(PerlIO *f,const char *mode, SV *arg);
-=item IV (*Pushed)(PerlIO *f,const char *mode,const char *arg,STRLEN len);
-
-Called when the layer is pushed onto the stack. The C<mode> argument may
-be NULL if this occurs post-open. The C<arg> and C<len> will be present
+The only absolutely mandatory method. Called when the layer is pushed onto the stack.
+The C<mode> argument may be NULL if this occurs post-open. The C<arg> will be non-C<NULL>
if an argument string was passed. In most cases this should call
C<PerlIOBase_pushed()> to convert C<mode> into the appropriate
C<PERLIO_F_XXXXX> 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<Getarg()> (it could perhaps C<Perl_warn> that the argument was un-expected).
=item IV (*Popped)(PerlIO *f);
closed if the program is dynamically managing layers on the stream. In
such cases C<Popped()> should free any resources (buffers, translation
tables, ...) not held directly in the layer's struct.
+It should also C<Unread()> 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<Open()> method has lots of arguments because it combines the functions
+of perl's C<open>, C<PerlIO_open>, perl's C<sysopen>, C<PerlIO_fdopen> and C<PerlIO_reopen>.
+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<PerlIO_allocate()> to allocate a slot in the table and
+associate it with the layers information for the opened file, by calling C<PerlIO_push>.
+The I<layers> AV is an array of all the layers destined for the C<PerlIO *>,
+and any arguments passed to them, I<n> is the index into that array of the
+layer being called. The macro C<PerlIOArg> will return a (possibly C<NULL>) SV *
+for the argument passed to the layer.
+
+The I<mode> string is an "C<fopen()>-like" string which would match the regular
+expression C</^[I#]?[rwa]\+?[bt]?$/>.
+
+The C<'I'> prefix is used during creation of C<stdin>..C<stderr> via special
+C<PerlIO_fdopen> calls; the C<'#'> prefix means that this is C<sysopen> and that I<imode> and
+I<perm> should be passed to C<PerlLIO_open3>; C<'r'> means B<r>ead, C<'w'> means B<w>rite
+and C<'a'> means B<a>ppend. 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<old> is not C<NULL> then this is a C<PerlIO_reopen>. Perl itself does not use
+this (yet?) and semantics are a little vague.
+
+If I<fd> not negative then it is the numeric file descriptor I<fd>, which will
+be open in a manner compatible with the supplied mode string, the call is
+thus equivalent to C<PerlIO_fdopen>. In this case I<nargs> will be zero.
+
+If I<nargs> is greater than zero then it gives the number of arguments passed
+to C<open>, otherwise it will be 1 if for example C<PerlIO_open> 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<Open()> at all,
+but rather leave the opening to a lower level layer and wait to be "pushed".
+If a layer does provide C<Open()> it should normally call the C<Open()> 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 (*Fileno)(PerlIO *f);
+
+Returns the Unix/Posix numeric file descriptor for the handle. Normally
+C<PerlIOBase_fileno()> (which just asks next layer down) will suffice
+for this.
=item SSize_t (*Read)(PerlIO *f, void *vbuf, Size_t count);
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<Unread()> such data to the lower layer.)
=item IV (*Fill)(PerlIO *f);
=item void (*Setlinebuf)(PerlIO *f);
-Mark the stream as line buffered.
+Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
+PERLIO_F_LINEBUF flag and is normally sufficient.
=item STDCHAR * (*Get_base)(PerlIO *f);
=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<layer> is the unknown layer. F<PerlIO.pm> will then attempt to :
+
+ require PerlIO::layer;
+
+If after that process the layer is still not defined then the C<open> 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<PerlIO.pm> "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<seek>, and determined via C<tell>.
+
+=item ":Object" or ":Perl"
+
+May be provided to allow layers to be implemented as perl code - implementation
+is being investigated.
+
+=back
=cut
projects / p5sagit/p5-mst-13.2.git / blobdiff