Debian Codegraph @

upstream/mageia-cauldron/man3pm/open.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 "open 3pm"
61 .TH open 3pm 2026-05-26 "perl v5.42.0" "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 open \- perl pragma to set default PerlIO layers for input and output
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 7
71 \& use open IN => \*(Aq:crlf\*(Aq, OUT => \*(Aq:raw\*(Aq;
72 \& open my $in, \*(Aq<\*(Aq, \*(Aqfoo.txt\*(Aq or die "open failed: $!";
73 \& my $line = <$in>; # CRLF translated
74 \& close $in;
75 \& open my $out, \*(Aq>\*(Aq, \*(Aqbar.txt\*(Aq or die "open failed: $!";
76 \& print $out $line; # no translation of bytes
77 \& close $out;
78 \&
79 \& use open OUT => \*(Aq:encoding(UTF\-8)\*(Aq;
80 \& use open IN => \*(Aq:encoding(iso\-8859\-7)\*(Aq;
81 \&
82 \& use open IO => \*(Aq:locale\*(Aq;
83 \&
84 \& # IO implicit only for :utf8, :encoding, :locale
85 \& use open \*(Aq:encoding(UTF\-8)\*(Aq;
86 \& use open \*(Aq:encoding(iso\-8859\-7)\*(Aq;
87 \& use open \*(Aq:locale\*(Aq;
88 \&
89 \& # with :std, also affect global standard handles
90 \& use open \*(Aq:std\*(Aq, \*(Aq:encoding(UTF\-8)\*(Aq;
91 \& use open \*(Aq:std\*(Aq, OUT => \*(Aq:encoding(cp1252)\*(Aq;
92 \& use open \*(Aq:std\*(Aq, IO => \*(Aq:raw :encoding(UTF\-16LE)\*(Aq;
93 .Ve
94 .SH DESCRIPTION
95 .IX Header "DESCRIPTION"
96 Full\-fledged support for I/O layers is now implemented provided
97 Perl is configured to use PerlIO as its IO system (which has been the
98 default since 5.8, and the only supported configuration since 5.16).
99 .PP
100 The \f(CW\*(C`open\*(C'\fR pragma serves as one of the interfaces to declare default
101 "layers" (previously known as "disciplines") for all I/O. Any \fBopen()\fR,
102 \&\fBreadpipe()\fR (aka qx//) and similar operators found within the
103 lexical scope of this pragma will use the declared defaults via the
104 \&\f(CW\*(C`${^OPEN}\*(C'\fR variable.
105 .PP
106 Layers are specified with a leading colon by convention. You can
107 specify a stack of multiple layers as a space\-separated string.
108 See PerlIO for more information on the available layers.
109 .PP
110 With the \f(CW\*(C`IN\*(C'\fR subpragma you can declare the default layers
111 of input streams, and with the \f(CW\*(C`OUT\*(C'\fR subpragma you can declare
112 the default layers of output streams. With the \f(CW\*(C`IO\*(C'\fR subpragma
113 (may be omitted for \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`:locale\*(C'\fR, or \f(CW\*(C`:encoding\*(C'\fR) you
114 can control both input and output streams simultaneously.
115 .PP
116 When \fBopen()\fR is given an explicit list of layers (with the three\-arg
117 syntax), they override the list declared using this pragma. \fBopen()\fR can
118 also be given a single colon (:) for a layer name, to override this pragma
119 and use the default as detailed in
120 "Defaults and how to override them" in PerlIO.
121 .PP
122 To translate from and to an arbitrary text encoding, use the \f(CW\*(C`:encoding\*(C'\fR
123 layer. The matching of encoding names in \f(CW\*(C`:encoding\*(C'\fR is loose: case does
124 not matter, and many encodings have several aliases. See
125 Encode::Supported for details and the list of supported locales.
126 .PP
127 If you want to set your encoding layers based on your
128 locale environment variables, you can use the \f(CW\*(C`:locale\*(C'\fR pseudo\-layer.
129 For example:
130 .PP
131 .Vb 9
132 \& $ENV{LANG} = \*(Aqru_RU.KOI8\-R\*(Aq;
133 \& # the :locale will probe the locale environment variables like LANG
134 \& use open OUT => \*(Aq:locale\*(Aq;
135 \& open(my $out, \*(Aq>\*(Aq, \*(Aqkoi8\*(Aq) or die "open failed: $!";
136 \& print $out chr(0x430); # CYRILLIC SMALL LETTER A = KOI8\-R 0xc1
137 \& close $out;
138 \& open(my $in, \*(Aq<\*(Aq, \*(Aqkoi8\*(Aq) or die "open failed: $!";
139 \& printf "%#x\en", ord(<$in>); # this should print 0xc1
140 \& close $in;
141 .Ve
142 .PP
143 The logic of \f(CW\*(C`:locale\*(C'\fR is described in full in
144 "The \f(CW\*(C`:locale\*(C'\fR sub\-pragma" in encoding,
145 but in short it is first trying nl_langinfo(CODESET) and then
146 guessing from the LC_ALL and LANG locale environment variables.
147 \&\f(CW\*(C`:locale\*(C'\fR also implicitly turns on \f(CW\*(C`:std\*(C'\fR.
148 .PP
149 \&\f(CW\*(C`:std\*(C'\fR is not a layer but an additional subpragma. When specified in the
150 import list, it activates an additional functionality of pushing the
151 layers selected for input/output handles to the standard filehandles
152 (STDIN, STDOUT, STDERR). If the new layers and existing layer stack both
153 end with an \f(CW\*(C`:encoding\*(C'\fR layer, the existing \f(CW\*(C`:encoding\*(C'\fR layer will also
154 be removed.
155 .PP
156 For example, if both input and out are chosen to be \f(CW:encoding(UTF\-8)\fR, a
157 \&\f(CW\*(C`:std\*(C'\fR will mean that STDIN, STDOUT, and STDERR will also have
158 \&\f(CW:encoding(UTF\-8)\fR set. On the other hand, if only output is chosen to
159 be in \f(CW:encoding(koi8r)\fR, a \f(CW\*(C`:std\*(C'\fR will cause only the STDOUT and STDERR
160 to be in \f(CW\*(C`koi8r\*(C'\fR.
161 .PP
162 The effect of \f(CW\*(C`:std\*(C'\fR is not lexical as it modifies the layer stack of the
163 global handles. If you wish to apply only this global effect and not the
164 effect on handles that are opened in that scope, you can isolate the call
165 to this pragma in its own lexical scope.
166 .PP
167 .Vb 1
168 \& { use open \*(Aq:std\*(Aq, IO => \*(Aq:encoding(UTF\-8)\*(Aq }
169 .Ve
170 .PP
171 Before Perl 5.34, \f(CW\*(C`:std\*(C'\fR would only apply the first layer provided that is
172 either \f(CW\*(C`:utf8\*(C'\fR or has a layer argument, e.g. \f(CW:encoding(UTF\-8)\fR. Since
173 Perl 5.34 it will apply the same layer stack it provides to \f(CW\*(C`${^OPEN}\*(C'\fR.
174 .SH "IMPLEMENTATION DETAILS"
175 .IX Header "IMPLEMENTATION DETAILS"
176 There is a class method in \f(CW\*(C`PerlIO::Layer\*(C'\fR \f(CW\*(C`find\*(C'\fR which is
177 implemented as XS code. It is called by \f(CW\*(C`import\*(C'\fR to validate the
178 layers:
179 .PP
180 .Vb 1
181 \& PerlIO::Layer::\->find("perlio")
182 .Ve
183 .PP
184 The return value (if defined) is a Perl object, of class
185 \&\f(CW\*(C`PerlIO::Layer\*(C'\fR which is created by the C code in \fIperlio.c\fR. As
186 yet there is nothing useful you can do with the object at the perl
187 level.
188 .SH "SEE ALSO"
189 .IX Header "SEE ALSO"
190 "binmode" in perlfunc, "open" in perlfunc, perlunicode, PerlIO,
191 encoding