open(3perl)

💖 open(3perl) — bestie edition 💖

okay so this is open(3perl) from the Perl Programmers Reference Guide, and babes, it's literally the pragma that sets your default PerlIO layers for input and output. sit with me, we're gonna go through it together 🫶

---

✨ NAME ✨

open — the perl pragma that sets default PerlIO layers for input and output 💅

---

✨ SYNOPSIS ✨

use open IN  => ':crlf', OUT => ':raw';
open my $in, '<', 'foo.txt' or die "open failed: $!";
my $line = <$in>; # CRLF translated
close $in;
open my $out, '>', 'bar.txt' or die "open failed: $!";
print $out $line; # no translation of bytes
close $out;

use open OUT => ':encoding(UTF-8)';
use open IN  => ':encoding(iso-8859-7)';

use open IO  => ':locale';

# IO implicit only for :utf8, :encoding, :locale
use open ':encoding(UTF-8)';
use open ':encoding(iso-8859-7)';
use open ':locale';

# with :std, also affect global standard handles
use open ':std', ':encoding(UTF-8)';
use open ':std', OUT => ':encoding(cp1252)';
use open ':std', IO => ':raw :encoding(UTF-16LE)';

like, look at that range. we've got :crlf, :raw, :encoding(UTF-8), :encoding(iso-8859-7), :locale, :std… the whole glow-up ✨

---

✨ DESCRIPTION ✨

so 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 is the only supported configuration since 5.16). periodt 💅

The open pragma serves as one of the interfaces to declare default "layers" (previously known as "disciplines" — yes the rebrand happened, iconic behavior) for all I/O. Any open(), readpipe() (aka qx//) and similar operators found within the lexical scope of this pragma will use the declared defaults via the ${^OPEN} variable. no cap 🔥

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 🦋

🌸 Subpragmas 🌸

• With the IN subpragma you can declare the default layers of input streams
• With the OUT subpragma you can declare the default layers of output streams
• With the IO subpragma (may be omitted for :utf8, :locale, or :encoding) you can control both input and output streams simultaneously 🌈

When open() is given an explicit list of layers (with the three-arg syntax), they override the list declared using this pragma. open() 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.

🎀 Encodings 🎀

To translate from and to an arbitrary text encoding, use the :encoding layer. The matching of encoding names in :encoding is loose: case does not matter, and many encodings have several aliases. See Encode::Supported for details and the list of supported locales 💜

If you want to set your encoding layers based on your locale environment variables, you can use the :locale pseudo-layer. For example:

$ENV{LANG} = 'ru_RU.KOI8-R';
# the :locale will probe the locale environment variables like LANG
use open OUT => ':locale';
open(my $out, '>', 'koi8') or die "open failed: $!";
print $out chr(0x430); # CYRILLIC SMALL LETTER A = KOI8-R 0xc1
close $out;
open(my $in, '<', 'koi8') or die "open failed: $!";
printf "%#x\n", ord(<$in>); # this should print 0xc1
close $in;

The logic of :locale is described in full in "The ":locale" 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. :locale also implicitly turns on :std 👑

💅 the :std subpragma 💅

:std 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 :encoding layer, the existing :encoding layer will also be removed.

For example, if both input and out are chosen to be :encoding(UTF-8), a :std will mean that STDIN, STDOUT, and STDERR will also have :encoding(UTF-8) set. On the other hand, if only output is chosen to be in :encoding(koi8r), a :std will cause only the STDOUT and STDERR to be in koi8r.

⚠️ bestie listen — the effect of :std is NOT lexical as it modifies the layer stack of the global handles. global. the whole vibe. 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.

{ use open ':std', IO => ':encoding(UTF-8)' }

Before Perl 5.34, :std would only apply the first layer provided that is either :utf8 or has a layer argument, e.g. :encoding(UTF-8). Since Perl 5.34 it will apply the same layer stack it provides to ${^OPEN}. glow up fr fr 🌟

---

✨ IMPLEMENTATION DETAILS ✨

There is a class method in PerlIO::Layer find which is implemented as XS code. It is called by import to validate the layers:

PerlIO::Layer::->find("perlio")

The return value (if defined) is a Perl object, of class PerlIO::Layer which is created by the C code in perlio.c. As yet there is nothing useful you can do with the object at the perl level 💀 — like okay, it's giving mysterious. it's giving untouchable. we move.

---

✨ SEE ALSO ✨

• "binmode" in perlfunc
• "open" in perlfunc
• perlunicode
• PerlIO
• encoding

---

and that's the whole page bestie!! 🦋💖

this was perl v5.44.0, dated 2026-10-17 — so if you're reading this, hi from the future, drink water, and go set your default layers responsibly 😭✌️ 🎀