Debian Codegraph @

upstream/debian-unstable/man3/PerlIO.3perl

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