| CARVIEW |
Select Language
HTTP/2 200
server: nginx
content-type: text/plain;charset=UTF-8
content-encoding: gzip
content-security-policy: default-src 'self'; connect-src 'self' *.google-analytics.com; img-src 'self' data: www.google-analytics.com www.googletagmanager.com; script-src 'self' 'unsafe-inline' www.google-analytics.com www.googletagmanager.com; style-src 'self'; report-uri /csp-reports
accept-ranges: bytes
age: 0
date: Mon, 13 Oct 2025 10:23:11 GMT
via: 1.1 varnish
x-served-by: cache-bom-vanm7210038-BOM
x-cache: MISS
x-cache-hits: 0
x-timer: S1760350990.398920,VS0,VE827
vary: Accept-Encoding
strict-transport-security: max-age=31557600
content-length: 7583
=over
=item open FILEHANDLE,MODE,EXPR
X X X X
=item open FILEHANDLE,MODE,EXPR,LIST
=item open FILEHANDLE,MODE,REFERENCE
=item open FILEHANDLE,EXPR
=item open FILEHANDLE
Associates an internal FILEHANDLE with the external file specified by
EXPR. That filehandle will subsequently allow you to perform
I/O operations on that file, such as reading from it or writing to it.
Instead of a filename, you may specify an external command
(plus an optional argument list) or a scalar reference, in order to open
filehandles on commands or in-memory scalars, respectively.
A thorough reference to C follows. For a gentler introduction to
the basics of C, see also the L manual page.
=over
=item Working with files
Most often, C gets invoked with three arguments: the required
FILEHANDLE (usually an empty scalar variable), followed by MODE (usually
a literal describing the I/O mode the filehandle will use), and then the
filename that the new filehandle will refer to.
=over
=item Simple examples
Reading from a file:
open(my $fh, "<", "input.txt")
or die "Can't open < input.txt: $!";
# Process every line in input.txt
while (my $line = readline($fh)) {
#
# ... do something interesting with $line here ...
#
}
or writing to one:
open(my $fh, ">", "output.txt")
or die "Can't open > output.txt: $!";
print $fh "This line gets printed into output.txt.\n";
For a summary of common filehandle operations such as these, see
L.
=item About filehandles
The first argument to C, labeled FILEHANDLE in this reference, is
usually a scalar variable. (Exceptions exist, described in "Other
considerations", below.) If the call to C succeeds, then the
expression provided as FILEHANDLE will get assigned an open
I. That filehandle provides an internal reference to the
specified external file, conveniently stored in a Perl variable, and
ready for I/O operations such as reading and writing.
=item About modes
When calling C with three or more arguments, the second argument
-- labeled MODE here -- defines the I. MODE is usually a
literal string comprising special characters that define the intended
I/O role of the filehandle being created: whether it's read-only, or
read-and-write, and so on.
If MODE is C<< < >>, the file is opened for input (read-only).
If MODE is C<< > >>, the file is opened for output, with existing files
first being truncated ("clobbered") and nonexisting files newly created.
If MODE is C<<< >> >>>, the file is opened for appending, again being
created if necessary.
You can put a C<+> in front of the C<< > >> or C<< < >> to
indicate that you want both read and write access to the file; thus
C<< +< >> is almost always preferred for read/write updates--the
C<< +> >> mode would clobber the file first. You can't usually use
either read-write mode for updating textfiles, since they have
variable-length records. See the B<-i> switch in
L for a better approach. The file is
created with permissions of C<0666> modified by the process's
L|/umask EXPR> value.
These various prefixes correspond to the L modes of C,
C, C, C, C, and C.
More examples of different modes in action:
# Open a file for concatenation
open(my $log, ">>", "/usr/spool/news/twitlog")
or warn "Couldn't open log file; discarding input";
# Open a file for reading and writing
open(my $dbase, "+<", "dbase.mine")
or die "Can't open 'dbase.mine' for update: $!";
=item Checking the return value
Open returns nonzero on success, the undefined value otherwise. If the
C involved a pipe, the return value happens to be the pid of the
subprocess.
When opening a file, it's seldom a good idea to continue if the request
failed, so C is frequently used with L|/die LIST>. Even if
you want your code to do something other than C on a failed open,
you should still always check the return value from opening a file.
=back
=item Specifying I/O layers in MODE
You can use the three-argument form of open to specify
I/O layers (sometimes referred to as "disciplines") to apply to the new
filehandle. These affect how the input and output are processed (see
L and
L for more details). For example:
# loads PerlIO::encoding automatically
open(my $fh, "<:encoding(UTF-8)", $filename)
|| die "Can't open UTF-8 encoded $filename: $!";
This opens the UTF8-encoded file containing Unicode characters;
see L. Note that if layers are specified in the
three-argument form, then default layers stored in
L|perlvar/${^OPEN}>
(usually set by the L pragma or the switch C<-CioD>) are ignored.
Those layers will also be ignored if you specify a colon with no name
following it. In that case the default layer for the operating system
(:raw on Unix, :crlf on Windows) is used.
On some systems (in general, DOS- and Windows-based systems)
L|/binmode FILEHANDLE, LAYER> is necessary when you're not
working with a text file. For the sake of portability it is a good idea
always to use it when appropriate, and never to use it when it isn't
appropriate. Also, people can set their I/O to be by default
UTF8-encoded Unicode, not bytes.
=item Using C for temporary files
As a special case the three-argument form with a read/write mode and the third
argument being L|/undef EXPR>:
open(my $tmp, "+>", undef) or die ...
opens a filehandle to a newly created empty anonymous temporary file.
(This happens under any mode, which makes C<< +> >> the only useful and
sensible mode to use.) You will need to
L|/seek FILEHANDLE,POSITION,WHENCE> to do the reading.
=item Opening a filehandle into an in-memory scalar
You can open filehandles directly to Perl scalars instead of a file or
other resource external to the program. To do so, provide a reference to
that scalar as the third argument to C, like so:
open(my $memory, ">", \$var)
or die "Can't open memory file: $!";
print $memory "foo!\n"; # output will appear in $var
To (re)open C or C as an in-memory file, close it first:
close STDOUT;
open(STDOUT, ">", \$variable)
or die "Can't open STDOUT: $!";
The scalars for in-memory files are treated as octet strings: unless
the file is being opened with truncation the scalar may not contain
any code points over 0xFF.
Opening in-memory files I fail for a variety of reasons. As with
any other C, check the return value for success.
I: This feature works only when Perl is built with
PerlIO -- the default, except with older (pre-5.16) Perl installations
that were configured to not include it (e.g. via C). You can see whether your Perl was built with PerlIO by
running C. If it says C<'define'>, you have PerlIO;
otherwise you don't.
See L for detailed info on PerlIO.
=item Opening a filehandle into a command
If MODE is C<|->, then the filename is
interpreted as a command to which output is to be piped, and if MODE
is C<-|>, the filename is interpreted as a command that pipes
output to us. In the two-argument (and one-argument) form, one should
replace dash (C<->) with the command.
See L for more examples of this.
(You are not allowed to C to a command
that pipes both in I out, but see L, L, and
L for
alternatives.)
open(my $article_fh, "-|", "caesar <$article") # decrypt
# article
or die "Can't start caesar: $!";
open(my $article_fh, "caesar <$article |") # ditto
or die "Can't start caesar: $!";
open(my $out_fh, "|-", "sort >Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
In the form of pipe opens taking three or more arguments, if LIST is specified
(extra arguments after the command name) then LIST becomes arguments
to the command invoked if the platform supports it. The meaning of
C with more than three arguments for
non-pipe modes is not yet defined, but experimental "layers" may give
extra LIST arguments meaning.
If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
with the one- or two-argument forms of
C), an implicit L|/fork> is done,
so C returns twice: in the parent process
it returns the pid
of the child process, and in the child process it returns (a defined) C<0>.
Use C or C to determine whether the open was successful.
For example, use either
my $child_pid = open(my $from_kid, "-|")
// die "Can't fork: $!";
or
my $child_pid = open(my $to_kid, "|-")
// die "Can't fork: $!";
followed by
if ($child_pid) {
# am the parent:
# either write $to_kid or else read $from_kid
...
waitpid $child_pid, 0;
} else {
# am the child; use STDIN/STDOUT normally
...
exit;
}
The filehandle behaves normally for the parent, but I/O to that
filehandle is piped from/to the STDOUT/STDIN of the child process.
In the child process, the filehandle isn't opened--I/O happens from/to
the new STDOUT/STDIN. Typically this is used like the normal
piped open when you want to exercise more control over just how the
pipe command gets executed, such as when running setuid and
you don't want to have to scan shell commands for metacharacters.
The following blocks are more or less equivalent:
open(my $fh, "|tr '[a-z]' '[A-Z]'");
open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
open(my $fh, "cat -n '$file'|");
open(my $fh, "-|", "cat -n '$file'");
open(my $fh, "-|") || exec "cat", "-n", $file;
open(my $fh, "-|", "cat", "-n", $file);
The last two examples in each block show the pipe as "list form", which
is not yet supported on all platforms. (If your platform has a real
L|/fork>, such as Linux and macOS, you can use the list form; it
also works on Windows with Perl 5.22 or later.) You would want to use
the list form of the pipe so you can pass literal arguments to the
command without risk of the shell interpreting any shell metacharacters
in them. However, this also bars you from opening pipes to commands that
intentionally contain shell metacharacters, such as:
open(my $fh, "|cat -n | expand -4 | lpr")
|| die "Can't open pipeline to lpr: $!";
See L for more examples of this.
=item Duping filehandles
You may also, in the Bourne shell tradition, specify an EXPR beginning
with C<< >& >>, in which case the rest of the string is interpreted
as the name of a filehandle (or file descriptor, if numeric) to be
duped (as in L) and opened. You may use C<&> after C<< > >>,
C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
The mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents
of IO buffers.) If you use the three-argument
form, then you can pass either a
number, the name of a filehandle, or the normal "reference to a glob".
Here is a script that saves, redirects, and restores C and
C using various methods:
#!/usr/bin/perl
open(my $oldout, ">&STDOUT")
or die "Can't dup STDOUT: $!";
open(OLDERR, ">&", \*STDERR)
or die "Can't dup STDERR: $!";
open(STDOUT, '>', "foo.out")
or die "Can't redirect STDOUT: $!";
open(STDERR, ">&STDOUT")
or die "Can't dup STDOUT: $!";
select STDERR; $| = 1; # make unbuffered
select STDOUT; $| = 1; # make unbuffered
print STDOUT "stdout 1\n"; # this works for
print STDERR "stderr 1\n"; # subprocesses too
open(STDOUT, ">&", $oldout)
or die "Can't dup \$oldout: $!";
open(STDERR, ">&OLDERR")
or die "Can't dup OLDERR: $!";
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
If you specify C<< '<&=X' >>, where C is a file descriptor number
or a filehandle, then Perl will do an equivalent of C's L of
that file descriptor (and not call L); this is more
parsimonious of file descriptors. For example:
# open for input, reusing the fileno of $fd
open(my $fh, "<&=", $fd)
or
open(my $fh, "<&=$fd")
or
# open for append, using the fileno of $oldfh
open(my $fh, ">>&=", $oldfh)
Being parsimonious on filehandles is also useful (besides being
parsimonious) for example when something is dependent on file
descriptors, like for example locking using
L|/flock FILEHANDLE,OPERATION>. If you do just
C<< open(my $A, ">>&", $B) >>, the filehandle C<$A> will not have the
same file descriptor as C<$B>, and therefore C will not
C nor vice versa. But with C<< open(my $A, ">>&=", $B) >>,
the filehandles will share the same underlying system file descriptor.
Note that under Perls older than 5.8.0, Perl uses the standard C library's'
L to implement the C<=> functionality. On many Unix systems,
L fails when file descriptors exceed a certain value, typically 255.
For Perls 5.8.0 and later, PerlIO is (most often) the default.
=item Legacy usage
This section describes ways to call C outside of best practices;
you may encounter these uses in older code. Perl does not consider their
use deprecated, exactly, but neither is it recommended in new code, for
the sake of clarity and readability.
=over
=item Specifying mode and filename as a single argument
In the one- and two-argument forms of the call, the mode and filename
should be concatenated (in that order), preferably separated by white
space. You can--but shouldn't--omit the mode in these forms when that mode
is C<< < >>. It is safe to use the two-argument form of
C if the filename argument is a known literal.
open(my $dbase, "+>
or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
New code should favor the three-argument form of C over this older
form. Declaring the mode and the filename as two distinct arguments
avoids any confusion between the two.
=item Assigning a filehandle to a bareword
An older style is to use a bareword as the filehandle, as
open(FH, "<", "input.txt")
or die "Can't open < input.txt: $!";
Then you can use C as the filehandle, in C<< close FH >> and C<<
>> and so on. Note that it's a global variable, so this form is
not recommended when dealing with filehandles other than Perl's built-in ones
(e.g. STDOUT and STDIN). In fact, using a bareword for the filehandle is
an error when the
L feature|feature/"The 'bareword_filehandles' feature">
has been disabled. This feature is disabled automatically when in the
scope of C