open(3pm)

1open(3pm)              Perl Programmers Reference Guide              open(3pm)
2
3
4

NAME

6       open - perl pragma to set default PerlIO layers for input and output
7

SYNOPSIS

9           use open IN  => ':crlf', OUT => ':raw';
10           open my $in, '<', 'foo.txt' or die "open failed: $!";
11           my $line = <$in>; # CRLF translated
12           close $in;
13           open my $out, '>', 'bar.txt' or die "open failed: $!";
14           print $out $line; # no translation of bytes
15           close $out;
16
17           use open OUT => ':encoding(UTF-8)';
18           use open IN  => ':encoding(iso-8859-7)';
19
20           use open IO  => ':locale';
21
22           # IO implicit only for :utf8, :encoding, :locale
23           use open ':encoding(UTF-8)';
24           use open ':encoding(iso-8859-7)';
25           use open ':locale';
26
27           # with :std, also affect global standard handles
28           use open ':std', ':encoding(UTF-8)';
29           use open ':std', OUT => ':encoding(cp1252)';
30           use open ':std', IO => ':raw :encoding(UTF-16LE)';
31

DESCRIPTION

33       Full-fledged support for I/O layers is now implemented provided Perl is
34       configured to use PerlIO as its IO system (which has been the default
35       since 5.8, and the only supported configuration since 5.16).
36
37       The "open" pragma serves as one of the interfaces to declare default
38       "layers" (previously known as "disciplines") for all I/O. Any open(),
39       readpipe() (aka qx//) and similar operators found within the lexical
40       scope of this pragma will use the declared defaults via the "${^OPEN}"
41       variable.
42
43       Layers are specified with a leading colon by convention. You can
44       specify a stack of multiple layers as a space-separated string.  See
45       PerlIO for more information on the available layers.
46
47       With the "IN" subpragma you can declare the default layers of input
48       streams, and with the "OUT" subpragma you can declare the default
49       layers of output streams.  With the "IO" subpragma (may be omitted for
50       ":utf8", ":locale", or ":encoding") you can control both input and
51       output streams simultaneously.
52
53       When open() is given an explicit list of layers (with the three-arg
54       syntax), they override the list declared using this pragma.  open() can
55       also be given a single colon (:) for a layer name, to override this
56       pragma and use the default as detailed in "Defaults and how to override
57       them" in PerlIO.
58
59       To translate from and to an arbitrary text encoding, use the
60       ":encoding" layer.  The matching of encoding names in ":encoding" is
61       loose: case does not matter, and many encodings have several aliases.
62       See Encode::Supported for details and the list of supported locales.
63
64       If you want to set your encoding layers based on your locale
65       environment variables, you can use the ":locale" pseudo-layer.  For
66       example:
67
68           $ENV{LANG} = 'ru_RU.KOI8-R';
69           # the :locale will probe the locale environment variables like LANG
70           use open OUT => ':locale';
71           open(my $out, '>', 'koi8') or die "open failed: $!";
72           print $out chr(0x430); # CYRILLIC SMALL LETTER A = KOI8-R 0xc1
73           close $out;
74           open(my $in, '<', 'koi8') or die "open failed: $!";
75           printf "%#x\n", ord(<$in>); # this should print 0xc1
76           close $in;
77
78       The logic of ":locale" is described in full in "The ":locale" sub-
79       pragma" in encoding, but in short it is first trying
80       nl_langinfo(CODESET) and then guessing from the LC_ALL and LANG locale
81       environment variables.  ":locale" also implicitly turns on ":std".
82
83       ":std" is not a layer but an additional subpragma.  When specified in
84       the import list, it activates an additional functionality of pushing
85       the layers selected for input/output handles to the standard
86       filehandles (STDIN, STDOUT, STDERR).  If the new layers and existing
87       layer stack both end with an ":encoding" layer, the existing
88       ":encoding" layer will also be removed.
89
90       For example, if both input and out are chosen to be ":encoding(UTF-8)",
91       a ":std" will mean that STDIN, STDOUT, and STDERR will also have
92       ":encoding(UTF-8)" set.  On the other hand, if only output is chosen to
93       be in ":encoding(koi8r)", a ":std" will cause only the STDOUT and
94       STDERR to be in "koi8r".
95
96       The effect of ":std" is not lexical as it modifies the layer stack of
97       the global handles.  If you wish to apply only this global effect and
98       not the effect on handles that are opened in that scope, you can
99       isolate the call to this pragma in its own lexical scope.
100
101           { use open ':std', IO => ':encoding(UTF-8)' }
102

IMPLEMENTATION DETAILS

104       There is a class method in "PerlIO::Layer" "find" which is implemented
105       as XS code.  It is called by "import" to validate the layers:
106
107          PerlIO::Layer::->find("perlio")
108
109       The return value (if defined) is a Perl object, of class
110       "PerlIO::Layer" which is created by the C code in perlio.c.  As yet
111       there is nothing useful you can do with the object at the perl level.
112

NAME

SYNOPSIS

DESCRIPTION

IMPLEMENTATION DETAILS

SEE ALSO