PerlIO::Layers - Querying your filehandle's capabilities
use PerlIO::Layers qw/query_handle/;
if (!query_handle(\*STDOUT, 'binary')) {
...
}
Perl's filehandles are implemented as a stack of layers, with the bottom-most
usually doing the actual IO and the higher ones doing buffering,
encoding/decoding or transformations. PerlIO::Layers allows you to query the
filehandle's properties concerning these layers.
This query a filehandle for some information. All queries can take an optional
argument, that will test for that layer's properties instead of all layers of
the handle. Currently supported queries include:
- layer
Check the presence of a certain layer. Unlike most other
properties $argument is mandatory for this
query.
- utf8
Check whether the filehandle/layer handles unicode
- crlf
Check whether the filehandle/layer does crlf translation
- binary
Check whether the filehandle/layer is binary. This test is
pessimistic (for unknown layers it will assume it's not binary).
- mappable
Checks whether the filehandle/layer is memory mappable. It is
the same as binary, except that the
"utf8" layer is accepted.
- buffered
Check whether the filehandle/layer is buffered.
- readable
Check whether the filehandle/layer is readable.
- writeable
Check whether the filehandle/layer is writeable.
- open
Check whether the filehandle/layer is open.
- temp
Check whether the filehandle/layer refers to a temporary
file.
- can_crlf
Checks whether layer $argument (or any
layer if $argument it not given) can do crlf
translation.
- line_buffered
Check whether the filehandle is in line-buffering mode.
- autoflush
Checks whether the filehandle is in unbuffering mode. Note
that this is not the opposite of buffering, but more similar to
autoflush, hence the name of this test.
- buffer_size
Check whether the buffer size is equal to
$argument.
Gets information on the layers of a filehandle. It's a list with whose entries
have 3 elements: the name of the layer, the arguments of the layer (may be
undef) and an arrayref with the flags of the layer as strings. The flags array
can contain any of these values:
- EOF
End of file has been reached.
- CANWRITE
Writes are permitted, i.e. opened as ">" or
"+<" or ">>", etc.
- CANREAD
Reads are permitted i.e. opened "<" or
"+>".
- ERROR
An error has occurred.
- TRUNCATE
Truncate file suggested by open mode.
- APPEND
All writes should be appends.
- CRLF
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. "binmode" will mess with this
flag rather than add/remove layers if the PERLIO_K_CANCRLF bit is set
for the layers class.
- UTF8
Data written to this layer should be UTF-8 encoded; data
provided by this layer should be considered UTF-8 encoded. Can be set on
any layer by ":utf8" dummy layer. Also set on
":encoding" layer.
- UNBUF
Layer is unbuffered - i.e. write to next layer down should
occur for each write to this layer.
- WRBUF
The buffer for this layer currently holds data written to it
but not sent to next layer.
- RDBUF
The buffer for this layer currently holds unconsumed data read
from layer below.
- 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.
- TEMP
File has been unlink()ed, or should be deleted on
close().
- OPEN
Handle is open.
- FASTGETS
This instance of this layer supports the "fast gets"
interface. Normally set based on PERLIO_K_FASTGETS 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.
"query_handle" provides a more
high level interface to this, you should probably use that when you can.
Returns a list of buffer sizes for all buffered layers. Unbuffered layers are
skipped.
Leon Timmermans <fawaka@gmail.com>
This software is copyright (c) 2010 by Leon Timmermans.
This is free software; you can redistribute it and/or modify it
under the same terms as the Perl 5 programming language system itself.