.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PerlIO::Layers 3pm"
.TH PerlIO::Layers 3pm "2016-06-20" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PerlIO::Layers \- Querying your filehandle's capabilities
.SH "VERSION"
.IX Header "VERSION"
version 0.011
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use PerlIO::Layers qw/query_handle/;
\&
\& if (!query_handle(\e*STDOUT, \*(Aqbinary\*(Aq)) {
\&     ...
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Perl's filehandles are implemented as a stack of layers, with the bottom-most usually doing the actual \s-1IO\s0 and the higher ones doing buffering, encoding/decoding or transformations. PerlIO::Layers allows you to query the filehandle's properties concerning these layers.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "query_handle($fh, $query_name [, $argument])"
.el .SS "query_handle($fh, \f(CW$query_name\fP [, \f(CW$argument\fP])"
.IX Subsection "query_handle($fh, $query_name [, $argument])"
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:
.IP "\(bu" 4
layer
.Sp
Check the presence of a certain layer. Unlike most other properties \f(CW$argument\fR is mandatory for this query.
.IP "\(bu" 4
utf8
.Sp
Check whether the filehandle/layer handles unicode
.IP "\(bu" 4
crlf
.Sp
Check whether the filehandle/layer does crlf translation
.IP "\(bu" 4
binary
.Sp
Check whether the filehandle/layer is binary. This test is pessimistic (for unknown layers it will assume it's not binary).
.IP "\(bu" 4
mappable
.Sp
Checks whether the filehandle/layer is memory mappable. It is the same as binary, except that the \f(CW\*(C`utf8\*(C'\fR layer is accepted.
.IP "\(bu" 4
buffered
.Sp
Check whether the filehandle/layer is buffered.
.IP "\(bu" 4
readable
.Sp
Check whether the filehandle/layer is readable.
.IP "\(bu" 4
writeable
.Sp
Check whether the filehandle/layer is writeable.
.IP "\(bu" 4
open
.Sp
Check whether the filehandle/layer is open.
.IP "\(bu" 4
temp
.Sp
Check whether the filehandle/layer refers to a temporary file.
.IP "\(bu" 4
can_crlf
.Sp
Checks whether layer \f(CW$argument\fR (or any layer if \f(CW$argument\fR it not given) can do crlf translation.
.IP "\(bu" 4
line_buffered
.Sp
Check whether the filehandle is in line-buffering mode.
.IP "\(bu" 4
autoflush
.Sp
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.
.IP "\(bu" 4
buffer_size
.Sp
Check whether the buffer size is equal to \f(CW$argument\fR.
.SS "get_layers($fh)"
.IX Subsection "get_layers($fh)"
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:
.IP "\(bu" 4
\&\s-1EOF\s0
.Sp
End of file has been reached.
.IP "\(bu" 4
\&\s-1CANWRITE\s0
.Sp
Writes are permitted, i.e. opened as \*(L">\*(R" or \*(L"+<\*(R" or \*(L">>\*(R", etc.
.IP "\(bu" 4
\&\s-1CANREAD\s0
.Sp
Reads are permitted i.e. opened \*(L"<\*(R" or \*(L"+>\*(R".
.IP "\(bu" 4
\&\s-1ERROR\s0
.Sp
An error has occurred.
.IP "\(bu" 4
\&\s-1TRUNCATE\s0
.Sp
Truncate file suggested by open mode.
.IP "\(bu" 4
\&\s-1APPEND\s0
.Sp
All writes should be appends.
.IP "\(bu" 4
\&\s-1CRLF\s0
.Sp
Layer is performing Win32\-like \*(L"\en\*(R" mapped to \s-1CR,LF\s0 for output and \s-1CR,LF\s0 mapped to \*(L"\en\*(R" for input. Normally the provided \*(L"crlf\*(R" layer is the only layer that need bother about this. \f(CW\*(C`binmode\*(C'\fR will mess with this flag rather than add/remove layers if the \s-1PERLIO_K_CANCRLF\s0 bit is set for the layers class.
.IP "\(bu" 4
\&\s-1UTF8\s0
.Sp
Data written to this layer should be \s-1UTF\-8\s0 encoded; data provided by this layer should be considered \s-1UTF\-8\s0 encoded. Can be set on any layer by \*(L":utf8\*(R" dummy layer. Also set on \*(L":encoding\*(R" layer.
.IP "\(bu" 4
\&\s-1UNBUF\s0
.Sp
Layer is unbuffered \- i.e. write to next layer down should occur for each write to this layer.
.IP "\(bu" 4
\&\s-1WRBUF\s0
.Sp
The buffer for this layer currently holds data written to it but not sent to next layer.
.IP "\(bu" 4
\&\s-1RDBUF\s0
.Sp
The buffer for this layer currently holds unconsumed data read from layer below.
.IP "\(bu" 4
\&\s-1LINEBUF\s0
.Sp
Layer is line buffered. Write data should be passed to next layer down whenever a \*(L"\en\*(R" is seen. Any data beyond the \*(L"\en\*(R" should then be processed.
.IP "\(bu" 4
\&\s-1TEMP\s0
.Sp
File has been \fIunlink()\fRed, or should be deleted on \fIclose()\fR.
.IP "\(bu" 4
\&\s-1OPEN\s0
.Sp
Handle is open.
.IP "\(bu" 4
\&\s-1FASTGETS\s0
.Sp
This instance of this layer supports the \*(L"fast gets\*(R" interface. Normally set based on \s-1PERLIO_K_FASTGETS\s0 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 \*(L"pending\*(R" layer needs to do this when it is pushed above a layer which does not support the interface.
.PP
\&\f(CW\*(C`query_handle\*(C'\fR provides a more high level interface to this, you should probably use that when you can.
.SS "get_buffer_sizes($fh)"
.IX Subsection "get_buffer_sizes($fh)"
Returns a list of buffer sizes for all buffered layers. Unbuffered layers are skipped.
.SH "AUTHOR"
.IX Header "AUTHOR"
Leon Timmermans <fawaka@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2010 by Leon Timmermans.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.