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,
int fd, int imode, int perm,
PerlIO *old,
int narg, SV **args);
+ IV (*Binmode)(pTHX_ 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)
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<malloc> 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<malloc> 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
=over 4
-=item char * name;
+=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<may> be able
+to tolerate layers compiled against an old version of the headers.
+
+=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:
and Perl knows that it has to invoke the PerlIOAPR_open() method
implemented by the APR layer.
-=item Size_t size;
+=item size
+
+ Size_t size;
The size of the per-instance data structure, e.g.:
sizeof(PerlIOAPR)
-=item IV kind;
+If this field is zero then C<PerlIO_pushed> 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<PerlIOl>,
+C<PerlIO_pushed> 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
- XXX: explain all the available flags here
+ IV kind;
=over 4
=item * PERLIO_K_BUFFERED
+The layer is buffered.
+
+=item * PERLIO_K_RAW
+
+The layer is acceptable to have in a binmode(FH) stack - i.e. it does not
+(or will configure itself not to) transform bytes passing through it.
+
=item * PERLIO_K_CANCRLF
+Layer can translate between "\n" and CRLF line ends.
+
=item * PERLIO_K_FASTGETS
+Layer allows buffer snooping.
+
=item * PERLIO_K_MULTIARG
Used when the layer's open() accepts more arguments than usual. The
extra arguments should come not before the C<MODE> argument. When this
flag is used it's up to the layer to validate the args.
-=item * PERLIO_K_RAW
-
=back
-=item IV (*Pushed)(pTHX_ PerlIO *f,const char *mode, SV *arg);
+=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<mode> argument may be NULL if this occurs
Returns 0 on success. On failure returns -1 and should set errno.
-=item IV (*Popped)(pTHX_ PerlIO *f);
+=item Popped
+
+ IV (*Popped)(pTHX_ PerlIO *f);
Called when the layer is popped from the stack. A layer will normally
be popped after C<Close()> is called. But a layer can be popped
Returns 0 on success and failure.
-=item PerlIO * (*Open)(...);
+=item Open
+
+ 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<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.)
+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<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.
Returns C<NULL> on failure.
-=item SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int flags)
+=item Binmode
+
+ IV (*Binmode)(pTHX_ PerlIO *f);
+
+Optional. Used when C<:raw> layer is pushed (explicitly or as a result
+of binmode(FH)). If not present layer will be popped. If present
+should configure layer as binary (or pop itself) and return 0.
+If it returns -1 for error C<binmode> will fail with layer
+still on the stack.
+
+=item Getarg
+
+ 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
"ascii". (I<param> and I<flags> arguments can be ignored in most
cases)
-=item IV (*Fileno)(pTHX_ PerlIO *f);
+=item Fileno
+
+ IV (*Fileno)(pTHX_ 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.
-Returns -1 if the layer cannot provide such a file descriptor, or in
-the case of the error.
+Returns -1 on error, which is considered to include the case where the
+layer cannot provide such a file descriptor.
+
+=item Dup
-XXX: two possible results end up in -1, one is an error the other is
-not.
+ PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
+ CLONE_PARAMS *param, int flags);
-=item PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flags)
+XXX: Needs more docs.
-XXX: not documented
+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<open>.
Similar to C<Open>, returns PerlIO* on success, C<NULL> on failure.
-=item SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
+=item Read
+
+ SSize_t (*Read)(pTHX_ PerlIO *f, void *vbuf, Size_t count);
Basic read operation.
Returns actual bytes read, or -1 on an error.
-=item SSize_t (*Unread)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
+=item Unread
+
+ SSize_t (*Unread)(pTHX_ PerlIO *f,
+ const void *vbuf, Size_t count);
A superset of stdio's C<ungetc()>. Should arrange for future reads to
see the bytes in C<vbuf>. If there is no obviously better implementation
Returns the number of unread chars.
-=item SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
+=item Write
+
+ SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);
Basic write operation.
Returns bytes written or -1 on an error.
-=item IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
+=item Seek
+
+ IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int whence);
Position the file pointer. Should normally call its own C<Flush>
method and then the C<Seek> method of next layer down.
Returns 0 on success, -1 on failure.
-=item Off_t (*Tell)(pTHX_ PerlIO *f);
+=item Tell
+
+ Off_t (*Tell)(pTHX_ PerlIO *f);
Return the file pointer. May be based on layers cached concept of
position to avoid overhead.
Returns -1 on failure to get the file pointer.
-=item IV (*Close)(pTHX_ PerlIO *f);
+=item Close
+
+ IV (*Close)(pTHX_ PerlIO *f);
Close the stream. Should normally call C<PerlIOBase_close()> to flush
itself and close layers below, and then deallocate any data structures
Returns 0 on success, -1 on failure.
-=item IV (*Flush)(pTHX_ PerlIO *f);
+=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
Returns 0 on success, -1 on failure.
-=item IV (*Fill)(pTHX_ PerlIO *f);
+=item Fill
+
+ 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
Returns 0 on success, -1 on failure.
-=item IV (*Eof)(pTHX_ PerlIO *f);
+=item Eof
+
+ IV (*Eof)(pTHX_ PerlIO *f);
Return end-of-file indicator. C<PerlIOBase_eof()> is normally sufficient.
Returns 0 on end-of-file, 1 if not end-of-file, -1 on error.
-=item IV (*Error)(pTHX_ PerlIO *f);
+=item Error
+
+ IV (*Error)(pTHX_ PerlIO *f);
Return error indicator. C<PerlIOBase_error()> is normally sufficient.
Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
0 otherwise.
-=item void (*Clearerr)(pTHX_ PerlIO *f);
+=item Clearerr
+
+ void (*Clearerr)(pTHX_ PerlIO *f);
Clear end-of-file and error indicators. Should call C<PerlIOBase_clearerr()>
to set the C<PERLIO_F_XXXXX> flags, which may suffice.
-=item void (*Setlinebuf)(pTHX_ PerlIO *f);
+=item Setlinebuf
+
+ void (*Setlinebuf)(pTHX_ PerlIO *f);
Mark the stream as line buffered. C<PerlIOBase_setlinebuf()> sets the
PERLIO_F_LINEBUF flag and is normally sufficient.
-=item STDCHAR * (*Get_base)(pTHX_ 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 NULL on failure.
-=item Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
+=item Get_bufsiz
+
+ Size_t (*Get_bufsiz)(pTHX_ PerlIO *f);
Return the number of bytes that last C<Fill()> put in the buffer.
-=item STDCHAR * (*Get_ptr)(pTHX_ 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)(pTHX_ 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)(pTHX_ 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<ptr> and/or C<cnt>.
The application (or layer above) must ensure they are consistent.
=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 C<PERLIO_K_RAW> bit set.
+"pushed" it actually pops the stack removing itself, it then calls
+Binmode function table entry on all the layers in the stack - normally
+this (via PerlIOBase_binmode) removes any layers which do not have
+C<PERLIO_K_RAW> bit set. Layers can modify that behaviour by defining
+their own Binmode entry.
=item "utf8"
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<seek>, and
determined via C<tell>.
-=item ":Object" or ":Perl"
+Please note that this layer is implied when calling open() thus:
+
+ open( $fh, "+<", \$scalar );
+
+=item ":via"
-May be provided to allow layers to be implemented as perl code -
-implementation is being investigated.
+Provided to allow layers to be implemented as Perl code. For instance:
+
+ use PerlIO::via::StripHTML;
+ open( my $fh, "<:via(StripHTML)", "index.html" );
+
+See L<PerlIO::via> for details.
=back
=back
=cut
-
-
-
projects / p5sagit/p5-mst-13.2.git / blobdiff