.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "open 3perl"
.TH open 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
open \- perl pragma to set default PerlIO layers for input and output
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\&    use open IN  => \*(Aq:crlf\*(Aq, OUT => \*(Aq:raw\*(Aq;
\&    open my $in, \*(Aq<\*(Aq, \*(Aqfoo.txt\*(Aq or die "open failed: $!";
\&    my $line = <$in>; # CRLF translated
\&    close $in;
\&    open my $out, \*(Aq>\*(Aq, \*(Aqbar.txt\*(Aq or die "open failed: $!";
\&    print $out $line; # no translation of bytes
\&    close $out;
\&
\&    use open OUT => \*(Aq:encoding(UTF\-8)\*(Aq;
\&    use open IN  => \*(Aq:encoding(iso\-8859\-7)\*(Aq;
\&
\&    use open IO  => \*(Aq:locale\*(Aq;
\&
\&    # IO implicit only for :utf8, :encoding, :locale
\&    use open \*(Aq:encoding(UTF\-8)\*(Aq;
\&    use open \*(Aq:encoding(iso\-8859\-7)\*(Aq;
\&    use open \*(Aq:locale\*(Aq;
\&
\&    # with :std, also affect global standard handles
\&    use open \*(Aq:std\*(Aq, \*(Aq:encoding(UTF\-8)\*(Aq;
\&    use open \*(Aq:std\*(Aq, OUT => \*(Aq:encoding(cp1252)\*(Aq;
\&    use open \*(Aq:std\*(Aq, IO => \*(Aq:raw :encoding(UTF\-16LE)\*(Aq;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Full-fledged support for I/O layers is now implemented provided
Perl is configured to use PerlIO as its IO system (which has been the
default since 5.8, and the only supported configuration since 5.16).
.PP
The \f(CW\*(C`open\*(C'\fR pragma serves as one of the interfaces to declare default
"layers" (previously known as "disciplines") for all I/O. Any \fBopen()\fR,
\&\fBreadpipe()\fR (aka qx//) and similar operators found within the
lexical scope of this pragma will use the declared defaults via the
\&\f(CW\*(C`${^OPEN}\*(C'\fR variable.
.PP
Layers are specified with a leading colon by convention. You can
specify a stack of multiple layers as a space-separated string.
See PerlIO for more information on the available layers.
.PP
With the \f(CW\*(C`IN\*(C'\fR subpragma you can declare the default layers
of input streams, and with the \f(CW\*(C`OUT\*(C'\fR subpragma you can declare
the default layers of output streams.  With the \f(CW\*(C`IO\*(C'\fR subpragma
(may be omitted for \f(CW\*(C`:utf8\*(C'\fR, \f(CW\*(C`:locale\*(C'\fR, or \f(CW\*(C`:encoding\*(C'\fR) you
can control both input and output streams simultaneously.
.PP
When \fBopen()\fR is given an explicit list of layers (with the three-arg
syntax), they override the list declared using this pragma.  \fBopen()\fR can
also be given a single colon (:) for a layer name, to override this pragma
and use the default as detailed in
"Defaults and how to override them" in PerlIO.
.PP
To translate from and to an arbitrary text encoding, use the \f(CW\*(C`:encoding\*(C'\fR
layer.  The matching of encoding names in \f(CW\*(C`:encoding\*(C'\fR is loose: case does
not matter, and many encodings have several aliases.  See
Encode::Supported for details and the list of supported locales.
.PP
If you want to set your encoding layers based on your
locale environment variables, you can use the \f(CW\*(C`:locale\*(C'\fR pseudo-layer.
For example:
.PP
.Vb 9
\&    $ENV{LANG} = \*(Aqru_RU.KOI8\-R\*(Aq;
\&    # the :locale will probe the locale environment variables like LANG
\&    use open OUT => \*(Aq:locale\*(Aq;
\&    open(my $out, \*(Aq>\*(Aq, \*(Aqkoi8\*(Aq) or die "open failed: $!";
\&    print $out chr(0x430); # CYRILLIC SMALL LETTER A = KOI8\-R 0xc1
\&    close $out;
\&    open(my $in, \*(Aq<\*(Aq, \*(Aqkoi8\*(Aq) or die "open failed: $!";
\&    printf "%#x\en", ord(<$in>); # this should print 0xc1
\&    close $in;
.Ve
.PP
The logic of \f(CW\*(C`:locale\*(C'\fR is described in full in
"The \f(CW\*(C`:locale\*(C'\fR sub-pragma" in encoding,
but in short it is first trying nl_langinfo(CODESET) and then
guessing from the LC_ALL and LANG locale environment variables.
\&\f(CW\*(C`:locale\*(C'\fR also implicitly turns on \f(CW\*(C`:std\*(C'\fR.
.PP
\&\f(CW\*(C`:std\*(C'\fR is not a layer but an additional subpragma.  When specified in the
import list, it activates an additional functionality of pushing the
layers selected for input/output handles to the standard filehandles
(STDIN, STDOUT, STDERR).  If the new layers and existing layer stack both
end with an \f(CW\*(C`:encoding\*(C'\fR layer, the existing \f(CW\*(C`:encoding\*(C'\fR layer will also
be removed.
.PP
For example, if both input and out are chosen to be \f(CW:encoding(UTF\-8)\fR, a
\&\f(CW\*(C`:std\*(C'\fR will mean that STDIN, STDOUT, and STDERR will also have
\&\f(CW:encoding(UTF\-8)\fR set.  On the other hand, if only output is chosen to
be in \f(CW:encoding(koi8r)\fR, a \f(CW\*(C`:std\*(C'\fR will cause only the STDOUT and STDERR
to be in \f(CW\*(C`koi8r\*(C'\fR.
.PP
The effect of \f(CW\*(C`:std\*(C'\fR is not lexical as it modifies the layer stack of the
global handles.  If you wish to apply only this global effect and not the
effect on handles that are opened in that scope, you can isolate the call
to this pragma in its own lexical scope.
.PP
.Vb 1
\&    { use open \*(Aq:std\*(Aq, IO => \*(Aq:encoding(UTF\-8)\*(Aq }
.Ve
.PP
Before Perl 5.34, \f(CW\*(C`:std\*(C'\fR would only apply the first layer provided that is
either \f(CW\*(C`:utf8\*(C'\fR or has a layer argument, e.g. \f(CW:encoding(UTF\-8)\fR. Since
Perl 5.34 it will apply the same layer stack it provides to \f(CW\*(C`${^OPEN}\*(C'\fR.
.SH "IMPLEMENTATION DETAILS"
.IX Header "IMPLEMENTATION DETAILS"
There is a class method in \f(CW\*(C`PerlIO::Layer\*(C'\fR \f(CW\*(C`find\*(C'\fR which is
implemented as XS code.  It is called by \f(CW\*(C`import\*(C'\fR to validate the
layers:
.PP
.Vb 1
\&   PerlIO::Layer::\->find("perlio")
.Ve
.PP
The return value (if defined) is a Perl object, of class
\&\f(CW\*(C`PerlIO::Layer\*(C'\fR which is created by the C code in \fIperlio.c\fR.  As
yet there is nothing useful you can do with the object at the perl
level.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
"binmode" in perlfunc, "open" in perlfunc, perlunicode, PerlIO,
encoding