1PerlIO::Layers(3)     User Contributed Perl Documentation    PerlIO::Layers(3)
2
3
4

NAME

6       PerlIO::Layers - Querying your filehandle's capabilities
7

VERSION

9       version 0.012
10

SYNOPSIS

12        use PerlIO::Layers qw/query_handle/;
13
14        if (!query_handle(\*STDOUT, 'binary')) {
15            ...
16        }
17

DESCRIPTION

19       Perl's filehandles are implemented as a stack of layers, with the
20       bottom-most usually doing the actual IO and the higher ones doing
21       buffering, encoding/decoding or transformations. PerlIO::Layers allows
22       you to query the filehandle's properties concerning these layers.
23

FUNCTIONS

25   query_handle($fh, $query_name [, $argument])
26       This query a filehandle for some information. All queries can take an
27       optional argument, that will test for that layer's properties instead
28       of all layers of the handle. Currently supported queries include:
29
30       •   layer
31
32           Check the presence of a certain layer. Unlike most other properties
33           $argument is mandatory for this query.
34
35       •   utf8
36
37           Check whether the filehandle/layer handles unicode
38
39       •   crlf
40
41           Check whether the filehandle/layer does crlf translation
42
43       •   binary
44
45           Check whether the filehandle/layer is binary. This test is
46           pessimistic (for unknown layers it will assume it's not binary).
47
48       •   mappable
49
50           Checks whether the filehandle/layer is memory mappable. It is the
51           same as binary, except that the "utf8" layer is accepted.
52
53       •   buffered
54
55           Check whether the filehandle/layer is buffered.
56
57       •   readable
58
59           Check whether the filehandle/layer is readable.
60
61       •   writeable
62
63           Check whether the filehandle/layer is writeable.
64
65       •   open
66
67           Check whether the filehandle/layer is open.
68
69       •   temp
70
71           Check whether the filehandle/layer refers to a temporary file.
72
73       •   can_crlf
74
75           Checks whether layer $argument (or any layer if $argument it not
76           given) can do crlf translation.
77
78       •   line_buffered
79
80           Check whether the filehandle is in line-buffering mode.
81
82       •   autoflush
83
84           Checks whether the filehandle is in unbuffering mode. Note that
85           this is not the opposite of buffering, but more similar to
86           autoflush, hence the name of this test.
87
88       •   buffer_size
89
90           Check whether the buffer size is equal to $argument.
91
92   get_layers($fh)
93       Gets information on the layers of a filehandle. It's a list with whose
94       entries have 3 elements: the name of the layer, the arguments of the
95       layer (may be undef) and an arrayref with the flags of the layer as
96       strings. The flags array can contain any of these values:
97
98       •   EOF
99
100           End of file has been reached.
101
102       •   CANWRITE
103
104           Writes are permitted, i.e. opened as ">" or "+<" or ">>", etc.
105
106       •   CANREAD
107
108           Reads are permitted i.e. opened "<" or "+>".
109
110       •   ERROR
111
112           An error has occurred.
113
114       •   TRUNCATE
115
116           Truncate file suggested by open mode.
117
118       •   APPEND
119
120           All writes should be appends.
121
122       •   CRLF
123
124           Layer is performing Win32-like "\n" mapped to CR,LF for output and
125           CR,LF mapped to "\n" for input. Normally the provided "crlf" layer
126           is the only layer that need bother about this. "binmode" will mess
127           with this flag rather than add/remove layers if the
128           PERLIO_K_CANCRLF bit is set for the layers class.
129
130       •   UTF8
131
132           Data written to this layer should be UTF-8 encoded; data provided
133           by this layer should be considered UTF-8 encoded. Can be set on any
134           layer by ":utf8" dummy layer. Also set on ":encoding" layer.
135
136       •   UNBUF
137
138           Layer is unbuffered - i.e. write to next layer down should occur
139           for each write to this layer.
140
141       •   WRBUF
142
143           The buffer for this layer currently holds data written to it but
144           not sent to next layer.
145
146       •   RDBUF
147
148           The buffer for this layer currently holds unconsumed data read from
149           layer below.
150
151       •   LINEBUF
152
153           Layer is line buffered. Write data should be passed to next layer
154           down whenever a "\n" is seen. Any data beyond the "\n" should then
155           be processed.
156
157       •   TEMP
158
159           File has been unlink()ed, or should be deleted on close().
160
161       •   OPEN
162
163           Handle is open.
164
165       •   FASTGETS
166
167           This instance of this layer supports the "fast gets" interface.
168           Normally set based on PERLIO_K_FASTGETS for the class and by the
169           existence of the function(s) in the table. However a class that
170           normally provides that interface may need to avoid it on a
171           particular instance. The "pending" layer needs to do this when it
172           is pushed above a layer which does not support the interface.
173
174       "query_handle" provides a more high level interface to this, you should
175       probably use that when you can.
176
177   get_buffer_sizes($fh)
178       Returns a list of buffer sizes for all buffered layers. Unbuffered
179       layers are skipped.
180

AUTHOR

182       Leon Timmermans <fawaka@gmail.com>
183

185       This software is copyright (c) 2010 by Leon Timmermans.
186
187       This is free software; you can redistribute it and/or modify it under
188       the same terms as the Perl 5 programming language system itself.
189
190
191
192perl v5.36.0                      2023-01-20                 PerlIO::Layers(3)
Impressum