=over

=item open FILEHANDLE,EXPR
X<open> X<pipe> X<file, open> X<fopen>

=item open FILEHANDLE,MODE,EXPR

=item open FILEHANDLE,MODE,EXPR,LIST

=item open FILEHANDLE,MODE,REFERENCE

=item open FILEHANDLE

Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.

Simple examples to open a file for reading:

    open(my $fh, "<", "input.txt") 
	or die "cannot open < input.txt: $!";

and for writing:

    open(my $fh, ">", "output.txt") 
	or die "cannot open > output.txt: $!";

(The following is a comprehensive reference to open(): for a gentler
introduction you may consider L<perlopentut>.)

If FILEHANDLE is an undefined scalar variable (or array or hash element), a
new filehandle is autovivified, meaning that the variable is assigned a
reference to a newly allocated anonymous filehandle.  Otherwise if
FILEHANDLE is an expression, its value is the real filehandle.  (This is
considered a symbolic reference, so C<use strict "refs"> should I<not> be
in effect.)

If EXPR is omitted, the global (package) scalar variable of the same
name as the FILEHANDLE contains the filename.  (Note that lexical 
variables--those declared with C<my> or C<state>--will not work for this
purpose; so if you're using C<my> or C<state>, specify EXPR in your
call to open.)

If three (or more) arguments are specified, the open mode (including
optional encoding) in the second argument are distinct from the filename in
the third.  If MODE is C<< < >> or nothing, the file is opened for input.
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<perlrun> for a
better approach.  The file is created with permissions of C<0666>
modified by the process's C<umask> value.

These various prefixes correspond to the fopen(3) modes of C<r>,
C<r+>, C<w>, C<w+>, C<a>, and C<a+>.

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 always safe to use the two-argument form of C<open> if
the filename argument is a known literal.

For three or more arguments if MODE is C<|->, 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<perlipc/"Using open() for IPC"> for more examples of this.
(You are not allowed to C<open> to a command that pipes both in I<and>
out, but see L<IPC::Open2>, L<IPC::Open3>, and
L<perlipc/"Bidirectional Communication with Another Process"> for
alternatives.)

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<open> with more than three arguments for non-pipe modes is not yet
defined, but experimental "layers" may give extra LIST arguments
meaning.

In the two-argument (and one-argument) form, opening C<< <- >> 
or C<-> opens STDIN and opening C<< >- >> opens STDOUT.

You may (and usually should) use the three-argument form of open to specify
I/O layers (sometimes referred to as "disciplines") to apply to the handle
that affect how the input and output are processed (see L<open> and
L<PerlIO> for more details).  For example:

  open(my $fh, "<:encoding(UTF-8)", "filename")
    || die "can't open UTF-8 encoded filename: $!";

opens the UTF8-encoded file containing Unicode characters;
see L<perluniintro>.  Note that if layers are specified in the
three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
Those layers will also be ignored if you specifying 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.

Open returns nonzero on success, the undefined value otherwise.  If
the C<open> involved a pipe, the return value happens to be the pid of
the subprocess.

If you're running Perl on a system that distinguishes between text
files and binary files, then you should check out L</binmode> for tips
for dealing with this.  The key distinction between systems that need
C<binmode> and those that don't is their text file formats.  Systems
like Unix, Mac OS, and Plan 9, that end lines with a single
character and encode that character in C as C<"\n"> do not
need C<binmode>.  The rest need it.

When opening a file, it's seldom a good idea to continue 
if the request failed, so C<open> is frequently used with
C<die>.  Even if C<die> won't do what you want (say, in a CGI script,
where you want to format a suitable error message (but there are
modules that can help with that problem)) always check
the return value from opening a file.  

As a special case the three-argument form with a read/write mode and the third
argument being C<undef>:

    open(my $tmp, "+>", undef) or die ...

opens a filehandle to an anonymous temporary file.  Also using C<< +< >>
works for symmetry, but you really should consider writing something
to the temporary file first.  You will need to seek() to do the
reading.

Since v5.8.0, Perl has built using PerlIO by default.  Unless you've
changed this (such as building Perl with C<Configure -Uuseperlio>), you can
open filehandles directly to Perl scalars via:

    open($fh, ">", \$variable) || ..

To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:

    close STDOUT;
    open(STDOUT, ">", \$variable)
	or die "Can't open STDOUT: $!";

General examples:

    $ARTICLE = 100;
    open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
    while (<ARTICLE>) {...

    open(LOG, ">>/usr/spool/news/twitlog");  # (log is reserved)
    # if the open fails, output is discarded

    open(my $dbase, "+<", "dbase.mine")      # open for update
        or die "Can't open 'dbase.mine' for update: $!";

    open(my $dbase, "+<dbase.mine")          # ditto
        or die "Can't open 'dbase.mine' for update: $!";

    open(ARTICLE, "-|", "caesar <$article")  # decrypt article
        or die "Can't start caesar: $!";

    open(ARTICLE, "caesar <$article |")      # ditto
        or die "Can't start caesar: $!";

    open(EXTRACT, "|sort >Tmp$$")            # $$ is our process id
        or die "Can't start sort: $!";

    # in-memory files
    open(MEMORY, ">", \$var)
        or die "Can't open memory file: $!";
    print MEMORY "foo!\n";                   # output will appear in $var

    # process argument list of files along with any includes

    foreach $file (@ARGV) {
        process($file, "fh00");
    }

    sub process {
        my($filename, $input) = @_;
        $input++;    # this is a string increment
        unless (open($input, "<", $filename)) {
            print STDERR "Can't open $filename: $!\n";
            return;
        }

        local $_;
        while (<$input>) {    # note use of indirection
            if (/^#include "(.*)"/) {
                process($1, $input);
                next;
            }
            #...          # whatever
        }
    }

See L<perliol> for detailed info on PerlIO.

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 C<dup(2)>) 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<STDOUT> and
C<STDERR> 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<X> is a file descriptor number
or a filehandle, then Perl will do an equivalent of C's C<fdopen> of
that file descriptor (and not call C<dup(2)>); this is more
parsimonious of file descriptors.  For example:

    # open for input, reusing the fileno of $fd
    open(FILEHANDLE, "<&=$fd")

or

    open(FILEHANDLE, "<&=", $fd)

or

    # open for append, using the fileno of OLDFH
    open(FH, ">>&=", OLDFH)

or

    open(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 flock().  If you do just
C<< open(A, ">>&B") >>, the filehandle A will not have the same file
descriptor as B, and therefore flock(A) will not flock(B) nor vice
versa.  But with C<< open(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'
fdopen() to implement the C<=> functionality.  On many Unix systems,
fdopen() fails when file descriptors exceed a certain value, typically 255.
For Perls 5.8.0 and later, PerlIO is (most often) the default.

You can see whether your Perl was built with PerlIO by running C<perl -V>
and looking for the C<useperlio=> line.  If C<useperlio> is C<define>, you
have PerlIO; otherwise you don't.

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<open>), 
an implicit C<fork> is done, so C<open> 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<defined($pid)> or C<//> to determine whether the open was successful.

For example, use either

    $child_pid = open(FROM_KID, "-|") 	// die "can't fork: $!";

or
    $child_pid = open(TO_KID,   "|-") 	// die "can't fork: $!";

followed by 

    if ($child_pid) {
	# am the parent:
	# either write TO_KID or else read FROM_KID
	...
	wait $child_pid;
    } 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(FOO, "|tr '[a-z]' '[A-Z]'");
    open(FOO, "|-", "tr '[a-z]' '[A-Z]'");
    open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
    open(FOO, "|-", "tr", '[a-z]', '[A-Z]');

    open(FOO, "cat -n '$file'|");
    open(FOO, "-|", "cat -n '$file'");
    open(FOO, "-|") || exec "cat", "-n", $file;
    open(FOO, "-|", "cat", "-n", $file);

The last two examples in each block show the pipe as "list form", which is
not yet supported on all platforms.  A good rule of thumb is that if
your platform has a real C<fork()> (in other words, if your platform is
Unix, including Linux and MacOS X), you can use the list form.  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(FOO, "|cat -n | expand -4 | lpr")
	// die "Can't open pipeline to lpr: $!";

See L<perlipc/"Safe Pipe Opens"> for more examples of this.

Beginning with v5.6.0, Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
supported on some platforms (see L<perlport>).  To be safe, you may need
to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
of C<IO::Handle> on any open handles.

On systems that support a close-on-exec flag on files, the flag will
be set for the newly opened file descriptor as determined by the value
of C<$^F>.  See L<perlvar/$^F>.

Closing any piped filehandle causes the parent process to wait for the
child to finish, then returns the status value in C<$?> and
C<${^CHILD_ERROR_NATIVE}>.

The filename passed to the one- and two-argument forms of open() will
have leading and trailing whitespace deleted and normal
redirection characters honored.  This property, known as "magic open",
can often be used to good effect.  A user could specify a filename of
F<"rsh cat file |">, or you could change certain filenames as needed:

    $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
    open(FH, $filename) or die "Can't open $filename: $!";

Use the three-argument form to open a file with arbitrary weird characters in it,

    open(FOO, "<", $file)
	|| die "can't open < $file: $!";

otherwise it's necessary to protect any leading and trailing whitespace:

    $file =~ s#^(\s)#./$1#;
    open(FOO, "< $file\0")
	|| die "open failed: $!";

(this may not work on some bizarre filesystems).  One should
conscientiously choose between the I<magic> and I<three-argument> form
of open():

    open(IN, $ARGV[0]) || die "can't open $ARGV[0]: $!";

will allow the user to specify an argument of the form C<"rsh cat file |">,
but will not work on a filename that happens to have a trailing space, while

    open(IN, "<", $ARGV[0])
	|| die "can't open < $ARGV[0]: $!";

will have exactly the opposite restrictions.

If you want a "real" C C<open> (see L<open(2)> on your system), then you
should use the C<sysopen> function, which involves no such magic (but may
use subtly different filemodes than Perl open(), which is mapped to C
fopen()).  This is another way to protect your filenames from
interpretation.  For example:

    use IO::Handle;
    sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL)
        or die "sysopen $path: $!";
    $oldfh = select(HANDLE); $| = 1; select($oldfh);
    print HANDLE "stuff $$\n";
    seek(HANDLE, 0, 0);
    print "File contains: ", <HANDLE>;

Using the constructor from the C<IO::Handle> package (or one of its
subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous
filehandles that have the scope of the variables used to hold them, then
automatically (but silently) close once their reference counts become
zero, typically at scope exit:

    use IO::File;
    #...
    sub read_myfile_munged {
        my $ALL = shift;
	# or just leave it undef to autoviv
        my $handle = IO::File->new;
        open($handle, "<", "myfile") or die "myfile: $!";
        $first = <$handle>
            or return ();     # Automatically closed here.
        mung($first) or die "mung failed";  # Or here.
        return (first, <$handle>) if $ALL;  # Or here.
        return $first;                      # Or here.
    }

B<WARNING:> The previous example has a bug because the automatic
close that happens when the refcount on C<handle> does not
properly detect and report failures.  I<Always> close the handle
yourself and inspect the return value.

    close($handle) 
	|| warn "close failed: $!";

See L</seek> for some details about mixing reading and writing.

Portability issues: L<perlport/open>.

=back