Debian Codegraph @

upstream/opensuse-tumbleweed/man3/PerlIO.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PerlIO 3pm"
61 .TH PerlIO 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 PerlIO \- On demand loader for PerlIO layers and root of PerlIO::* name space
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& # support platform\-native and CRLF text files
72 \& open(my $fh, "<:crlf", "my.txt") or die "open failed: $!";
73 \&
74 \& # append UTF\-8 encoded text
75 \& open(my $fh, ">>:encoding(UTF\-8)", "some.log")
76 \& or die "open failed: $!";
77 \&
78 \& # portably open a binary file for reading
79 \& open(my $fh, "<", "his.jpg") or die "open failed: $!";
80 \& binmode($fh) or die "binmode failed: $!";
81 \&
82 \& Shell:
83 \& PERLIO=:perlio perl ....
84 .Ve
85 .SH DESCRIPTION
86 .IX Header "DESCRIPTION"
87 When an undefined layer \*(Aqfoo\*(Aq is encountered in an \f(CW\*(C`open\*(C'\fR or
88 \&\f(CW\*(C`binmode\*(C'\fR layer specification then C code performs the equivalent of:
89 .PP
90 .Vb 1
91 \& use PerlIO \*(Aqfoo\*(Aq;
92 .Ve
93 .PP
94 The Perl code in PerlIO.pm then attempts to locate a layer by doing
95 .PP
96 .Vb 1
97 \& require PerlIO::foo;
98 .Ve
99 .PP
100 Otherwise the \f(CW\*(C`PerlIO\*(C'\fR package is a place holder for additional
101 PerlIO related functions.
102 .SS Layers
103 .IX Subsection "Layers"
104 Generally speaking, PerlIO layers (previously sometimes referred to as
105 "disciplines") are an ordered stack applied to a filehandle (specified as
106 a space\- or colon\-separated list, conventionally written with a leading
107 colon). Each layer performs some operation on any input or output, except
108 when bypassed such as with \f(CW\*(C`sysread\*(C'\fR or \f(CW\*(C`syswrite\*(C'\fR. Read operations go
109 through the stack in the order they are set (left to right), and write
110 operations in the reverse order.
111 .PP
112 There are also layers which actually just set flags on lower layers, or
113 layers that modify the current stack but don\*(Aqt persist on the stack
114 themselves; these are referred to as pseudo\-layers.
115 .PP
116 When opening a handle, it will be opened with any layers specified
117 explicitly in the \fBopen()\fR call (or the platform defaults, if specified as
118 a colon with no following layers).
119 .PP
120 If layers are not explicitly specified, the handle will be opened with the
121 layers specified by the ${^OPEN} variable (usually
122 set by using the open pragma for a lexical scope, or the \f(CW\*(C`\-C\*(C'\fR
123 command\-line switch or \f(CW\*(C`PERL_UNICODE\*(C'\fR environment variable for the main
124 program scope).
125 .PP
126 If layers are not specified in the \fBopen()\fR call or \f(CW\*(C`${^OPEN}\*(C'\fR variable,
127 the handle will be opened with the default layer stack configured for that
128 architecture; see "Defaults and how to override them".
129 .PP
130 Some layers will automatically insert required lower level layers if not
131 present; for example \f(CW\*(C`:perlio\*(C'\fR will insert \f(CW\*(C`:unix\*(C'\fR below itself for low
132 level IO, and \f(CW\*(C`:encoding\*(C'\fR will insert the platform defaults for buffered
133 IO.
134 .PP
135 The \f(CW\*(C`binmode\*(C'\fR function can be called on an opened handle to push
136 additional layers onto the stack, which may also modify the existing
137 layers. \f(CW\*(C`binmode\*(C'\fR called with no layers will remove or unset any
138 existing layers which transform the byte stream, making the handle
139 suitable for binary data.
140 .PP
141 The following layers are currently defined:
142 .IP :unix 4
143 .IX Item ":unix"
144 Lowest level layer which provides basic PerlIO operations in terms of
145 UNIX/POSIX numeric file descriptor calls
146 (\fBopen()\fR, \fBread()\fR, \fBwrite()\fR, \fBlseek()\fR, \fBclose()\fR).
147 It is used even on non\-Unix architectures, and most other layers operate on
148 top of it.
149 .IP :stdio 4
150 .IX Item ":stdio"
151 Layer which calls \f(CW\*(C`fread\*(C'\fR, \f(CW\*(C`fwrite\*(C'\fR and \f(CW\*(C`fseek\*(C'\fR/\f(CW\*(C`ftell\*(C'\fR etc. Note
152 that as this is "real" stdio it will ignore any layers beneath it and
153 go straight to the operating system via the C library as usual.
154 This layer implements both low level IO and buffering, but is rarely used
155 on modern architectures.
156 .IP :perlio 4
157 .IX Item ":perlio"
158 A from scratch implementation of buffering for PerlIO. Provides fast
159 access to the buffer for \f(CW\*(C`sv_gets\*(C'\fR which implements Perl\*(Aqs readline/<>
160 and in general attempts to minimize data copying.
161 .Sp
162 \&\f(CW\*(C`:perlio\*(C'\fR will insert a \f(CW\*(C`:unix\*(C'\fR layer below itself to do low level IO.
163 .IP :crlf 4
164 .IX Item ":crlf"
165 A layer that implements DOS/Windows like CRLF line endings. On read
166 converts pairs of CR,LF to a single "\en" newline character. On write
167 converts each "\en" to a CR,LF pair. Note that this layer will silently
168 refuse to be pushed on top of itself.
169 .Sp
170 It currently does \fInot\fR mimic MS\-DOS as far as treating of Control\-Z
171 as being an end\-of\-file marker.
172 .Sp
173 On DOS/Windows like architectures where this layer is part of the defaults,
174 it also acts like the \f(CW\*(C`:perlio\*(C'\fR layer, and removing the CRLF translation
175 (such as with \f(CW\*(C`:raw\*(C'\fR) will only unset the CRLF translation flag. Since
176 Perl 5.14, you can also apply another \f(CW\*(C`:crlf\*(C'\fR layer later, such as when
177 the CRLF translation must occur after an encoding layer. On other
178 architectures, it is a mundane CRLF translation layer and can be added and
179 removed normally.
180 .Sp
181 .Vb 3
182 \& # translate CRLF after encoding on Perl 5.14 or newer
183 \& binmode $fh, ":raw:encoding(UTF\-16LE):crlf"
184 \& or die "binmode failed: $!";
185 .Ve
186 .IP :utf8 4
187 .IX Item ":utf8"
188 Pseudo\-layer that declares that the stream accepts Perl\*(Aqs \fIinternal\fR
189 upgraded encoding of characters, which is approximately UTF\-8 on ASCII
190 machines, but UTF\-EBCDIC on EBCDIC machines. This allows any character
191 Perl can represent to be read from or written to the stream.
192 .Sp
193 This layer (which actually sets a flag on the preceding layer, and is
194 implicitly set by any \f(CW\*(C`:encoding\*(C'\fR layer) does not translate or validate
195 byte sequences. It instead indicates that the byte stream will have been
196 arranged by other layers to be provided in Perl\*(Aqs internal upgraded
197 encoding, which Perl code (and correctly written XS code) will interpret
198 as decoded Unicode characters.
199 .Sp
200 \&\fBCAUTION\fR: Do not use this layer to translate from UTF\-8 bytes, as
201 invalid UTF\-8 or binary data will result in malformed Perl strings. It is
202 unlikely to produce invalid UTF\-8 when used for output, though it will
203 instead produce UTF\-EBCDIC on EBCDIC systems. The \f(CW:encoding(UTF\-8)\fR
204 layer (hyphen is significant) is preferred as it will ensure translation
205 between valid UTF\-8 bytes and valid Unicode characters.
206 .IP :bytes 4
207 .IX Item ":bytes"
208 This is the inverse of the \f(CW\*(C`:utf8\*(C'\fR pseudo\-layer. It turns off the flag
209 on the layer below so that data read from it is considered to
210 be Perl\*(Aqs internal downgraded encoding, thus interpreted as the native
211 single\-byte encoding of Latin\-1 or EBCDIC. Likewise on output Perl will
212 warn if a "wide" character (a codepoint not in the range 0..255) is
213 written to a such a stream.
214 .Sp
215 This is very dangerous to push on a handle using an \f(CW\*(C`:encoding\*(C'\fR layer,
216 as such a layer assumes to be working with Perl\*(Aqs internal upgraded
217 encoding, so you will likely get a mangled result. Instead use \f(CW\*(C`:raw\*(C'\fR or
218 \&\f(CW\*(C`:pop\*(C'\fR to remove encoding layers.
219 .IP :raw 4
220 .IX Item ":raw"
221 The \f(CW\*(C`:raw\*(C'\fR pseudo\-layer is \fIdefined\fR as being identical to calling
222 \&\f(CWbinmode($fh)\fR \- the stream is made suitable for passing binary data,
223 i.e. each byte is passed as\-is. The stream will still be buffered
224 (but this was not always true before Perl 5.14).
225 .Sp
226 In Perl 5.6 and some books the \f(CW\*(C`:raw\*(C'\fR layer is documented as the inverse
227 of the \f(CW\*(C`:crlf\*(C'\fR layer. That is no longer the case \- other layers which
228 would alter the binary nature of the stream are also disabled. If you
229 want UNIX line endings on a platform that normally does CRLF translation,
230 but still want UTF\-8 or encoding defaults, the appropriate thing to do is
231 to add \f(CW\*(C`:perlio\*(C'\fR to the PERLIO environment variable, or open the handle
232 explicitly with that layer, to replace the platform default of \f(CW\*(C`:crlf\*(C'\fR.
233 .Sp
234 The implementation of \f(CW\*(C`:raw\*(C'\fR is as a pseudo\-layer which when "pushed"
235 pops itself and then any layers which would modify the binary data stream.
236 (Undoing \f(CW\*(C`:utf8\*(C'\fR and \f(CW\*(C`:crlf\*(C'\fR may be implemented by clearing flags
237 rather than popping layers but that is an implementation detail.)
238 .Sp
239 As a consequence of the fact that \f(CW\*(C`:raw\*(C'\fR normally pops layers,
240 it usually only makes sense to have it as the only or first element in
241 a layer specification. When used as the first element it provides
242 a known base on which to build e.g.
243 .Sp
244 .Vb 2
245 \& open(my $fh,">:raw:encoding(UTF\-8)",...)
246 \& or die "open failed: $!";
247 .Ve
248 .Sp
249 will construct a "binary" stream regardless of the platform defaults,
250 but then enable UTF\-8 translation.
251 .IP :pop 4
252 .IX Item ":pop"
253 A pseudo\-layer that removes the top\-most layer. Gives Perl code a
254 way to manipulate the layer stack. Note that \f(CW\*(C`:pop\*(C'\fR only works on
255 real layers and will not undo the effects of pseudo\-layers or flags
256 like \f(CW\*(C`:utf8\*(C'\fR. An example of a possible use might be:
257 .Sp
258 .Vb 7
259 \& open(my $fh,...) or die "open failed: $!";
260 \& ...
261 \& binmode($fh,":encoding(...)") or die "binmode failed: $!";
262 \& # next chunk is encoded
263 \& ...
264 \& binmode($fh,":pop") or die "binmode failed: $!";
265 \& # back to un\-encoded
266 .Ve
267 .Sp
268 A more elegant (and safer) interface is needed.
269 .SS "Custom Layers"
270 .IX Subsection "Custom Layers"
271 It is possible to write custom layers in addition to the above builtin
272 ones, both in C/XS and Perl, as a module named \f(CW\*(C`PerlIO::<layer name>\*(C'\fR.
273 Some custom layers come with the Perl distribution.
274 .IP :encoding 4
275 .IX Item ":encoding"
276 Use \f(CW:encoding(ENCODING)\fR to transparently do character set and encoding
277 transformations, for example from Shift\-JIS to Unicode. Note that an
278 \&\f(CW\*(C`:encoding\*(C'\fR also enables \f(CW\*(C`:utf8\*(C'\fR. See PerlIO::encoding for more
279 information.
280 .IP :mmap 4
281 .IX Item ":mmap"
282 A layer which implements "reading" of files by using \f(CWmmap()\fR to
283 make a (whole) file appear in the process\*(Aqs address space, and then
284 using that as PerlIO\*(Aqs "buffer". This \fImay\fR be faster in certain
285 circumstances for large files, and may result in less physical memory
286 use when multiple processes are reading the same file.
287 .Sp
288 Files which are not \f(CWmmap()\fR\-able revert to behaving like the \f(CW\*(C`:perlio\*(C'\fR
289 layer. Writes also behave like the \f(CW\*(C`:perlio\*(C'\fR layer, as \f(CWmmap()\fR for write
290 needs extra house\-keeping (to extend the file) which negates any advantage.
291 .Sp
292 The \f(CW\*(C`:mmap\*(C'\fR layer will not exist if the platform does not support \f(CWmmap()\fR.
293 See PerlIO::mmap for more information.
294 .IP :via 4
295 .IX Item ":via"
296 \&\f(CW:via(MODULE)\fR allows a transformation to be applied by an arbitrary Perl
297 module, for example compression / decompression, encryption / decryption.
298 See PerlIO::via for more information.
299 .IP :scalar 4
300 .IX Item ":scalar"
301 A layer implementing "in memory" files using scalar variables,
302 automatically used in place of the platform defaults for IO when opening
303 such a handle. As such, the scalar is expected to act like a file, only
304 containing or storing bytes. See PerlIO::scalar for more information.
305 .SS "Alternatives to raw"
306 .IX Subsection "Alternatives to raw"
307 To get a binary stream an alternate method is to use:
308 .PP
309 .Vb 2
310 \& open(my $fh,"<","whatever") or die "open failed: $!";
311 \& binmode($fh) or die "binmode failed: $!";
312 .Ve
313 .PP
314 This has the advantage of being backward compatible with older versions
315 of Perl that did not use PerlIO or where \f(CW\*(C`:raw\*(C'\fR was buggy (as it was
316 before Perl 5.14).
317 .PP
318 To get an unbuffered stream specify an unbuffered layer (e.g. \f(CW\*(C`:unix\*(C'\fR)
319 in the open call:
320 .PP
321 .Vb 1
322 \& open(my $fh,"<:unix",$path) or die "open failed: $!";
323 .Ve
324 .SS "Defaults and how to override them"
325 .IX Subsection "Defaults and how to override them"
326 If the platform is MS\-DOS like and normally does CRLF to "\en"
327 translation for text files then the default layers are:
328 .PP
329 .Vb 1
330 \& :unix:crlf
331 .Ve
332 .PP
333 Otherwise if \f(CW\*(C`Configure\*(C'\fR found out how to do "fast" IO using the system\*(Aqs
334 stdio (not common on modern architectures), then the default layers are:
335 .PP
336 .Vb 1
337 \& :stdio
338 .Ve
339 .PP
340 Otherwise the default layers are
341 .PP
342 .Vb 1
343 \& :unix:perlio
344 .Ve
345 .PP
346 Note that the "default stack" depends on the operating system and on the
347 Perl version, and both the compile\-time and runtime configurations of
348 Perl. The default can be overridden by setting the environment variable
349 PERLIO to a space or colon separated list of layers, however this cannot
350 be used to set layers that require loading modules like \f(CW\*(C`:encoding\*(C'\fR.
351 .PP
352 This can be used to see the effect of/bugs in the various layers e.g.
353 .PP
354 .Vb 3
355 \& cd .../perl/t
356 \& PERLIO=:stdio ./perl harness
357 \& PERLIO=:perlio ./perl harness
358 .Ve
359 .PP
360 For the various values of PERLIO see "PERLIO" in perlrun.
361 .PP
362 The following table summarizes the default layers on UNIX\-like and
363 DOS\-like platforms and depending on the setting of \f(CW$ENV{PERLIO}\fR:
364 .PP
365 .Vb 5
366 \& PERLIO UNIX\-like DOS\-like
367 \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-
368 \& unset / "" :unix:perlio / :stdio [1] :unix:crlf
369 \& :stdio :stdio :stdio
370 \& :perlio :unix:perlio :unix:perlio
371 \&
372 \& # [1] ":stdio" if Configure found out how to do "fast stdio" (depends
373 \& # on the stdio implementation) and in Perl 5.8, else ":unix:perlio"
374 .Ve
375 .SS "Querying the layers of filehandles"
376 .IX Subsection "Querying the layers of filehandles"
377 The following returns the \fBnames\fR of the PerlIO layers on a filehandle.
378 .PP
379 .Vb 1
380 \& my @layers = PerlIO::get_layers($fh); # Or FH, *FH, "FH".
381 .Ve
382 .PP
383 The layers are returned in the order an \fBopen()\fR or \fBbinmode()\fR call would
384 use them, and without colons.
385 .PP
386 By default the layers from the input side of the filehandle are
387 returned; to get the output side, use the optional \f(CW\*(C`output\*(C'\fR argument:
388 .PP
389 .Vb 1
390 \& my @layers = PerlIO::get_layers($fh, output => 1);
391 .Ve
392 .PP
393 (Usually the layers are identical on either side of a filehandle but
394 for example with sockets there may be differences.)
395 .PP
396 There is no \fBset_layers()\fR, nor does \fBget_layers()\fR return a tied array
397 mirroring the stack, or anything fancy like that. This is not
398 accidental or unintentional. The PerlIO layer stack is a bit more
399 complicated than just a stack (see for example the behaviour of \f(CW\*(C`:raw\*(C'\fR).
400 You are supposed to use \fBopen()\fR and \fBbinmode()\fR to manipulate the stack.
401 .PP
402 \&\fBImplementation details follow, please close your eyes.\fR
403 .PP
404 The arguments to layers are by default returned in parentheses after
405 the name of the layer, and certain layers (like \f(CW\*(C`:utf8\*(C'\fR) are not real
406 layers but instead flags on real layers; to get all of these returned
407 separately, use the optional \f(CW\*(C`details\*(C'\fR argument:
408 .PP
409 .Vb 1
410 \& my @layer_and_args_and_flags = PerlIO::get_layers($fh, details => 1);
411 .Ve
412 .PP
413 The result will be up to be three times the number of layers:
414 the first element will be a name, the second element the arguments
415 (unspecified arguments will be \f(CW\*(C`undef\*(C'\fR), the third element the flags,
416 the fourth element a name again, and so forth.
417 .PP
418 \&\fBYou may open your eyes now.\fR
419 .SH AUTHOR
420 .IX Header "AUTHOR"
421 Nick Ing\-Simmons <nick@ing\-simmons.net>
422 .SH "SEE ALSO"
423 .IX Header "SEE ALSO"
424 "binmode" in perlfunc, "open" in perlfunc, perlunicode, perliol,
425 Encode