open - open a file, pipe, or descriptor
open FILEHANDLE,EXPR
open FILEHANDLE
Opens the file whose filename is given by EXPR, and associates it with FILEHANDLE. If FILEHANDLE is an expression, its value is used as the name of the real filehandle wanted. If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE contains the filename. (Note that lexical variables--those declared with my()--will not work for this purpose; so if you're using my(), specify EXPR in your call to open.)
If the filename begins with '<' or nothing, the file is opened for input. If the filename begins with '>', the file is truncated and opened for output, being created if necessary.
If the filename begins with '>>', the file is opened for appending, again being created if necessary. You
can put a '+' in front of the '>' or '<' to indicate that you want both read and write access to the file; thus '+<' is almost always preferred for read/write updates--the '+>' 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 -i
switch in the perlrun manpage for a better approach.
The prefix and the filename may be separated with spaces. These various prefixes correspond to the
fopen(3) modes of
'r', 'r+', 'w',
'w+', 'a', and 'a+'.
If the filename begins with '|', the filename is interpreted as a command to which output is to be piped,
and if the filename ends with a
'|', the filename is interpreted See Using open() for IPC
for more examples of this. (You are not allowed to open() to a command that pipes both in and out, but see Open2, Open3, and Bidirectional Communication for alternatives.)
Opening '-' opens
STDIN and opening '>-' opens
STDOUT. Open returns nonzero upon success, the
undefined value otherwise. If the open()
involved a pipe, the return value happens to be the pid of the subprocess.
If you're unfortunate enough to be running Perl on a system that
distinguishes between text files and binary files (modern operating systems
don't care), then you should check out binmode for tips for dealing with this. The key distinction between systems that
need binmode()
and those that don't is their text file formats. Systems like Unix, MacOS, and Plan9, which delimit lines with a single character, and which encode that character in
C as
"\n", do not need binmode(). The rest need it.
When opening a file, it's usually a bad idea to continue normal execution if the request failed, so open() is frequently used in connection with die(). Even if die() won't do what you want (say, in a CGI script, where you want to make a nicely formatted error message (but there are modules that can help with that problem)) you should always check the return value from opening a file. The infrequent exception is when working with an unopened filehandle is actually what you want to do.
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(DBASE, '+<dbase.mine') # open for update
or die "Can't open 'dbase.mine' for update: $!";
open(ARTICLE, "caesar <$article |") # decrypt article
or die "Can't start caesar: $!";
open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id
or die "Can't start sort: $!";
# 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
}
}
You may also, in the Bourne shell tradition, specify an
EXPR beginning with '>&', in which case the rest of the string is interpreted as the name of a
filehandle (or file descriptor, if numeric) to be duped and opened. You may
use & after >, >>, <, +>,
+>>, and +<. The mode you specify should match the mode of the original filehandle. (Duping a filehandle does not take into account any existing contents of stdio buffers.) Here is a script that saves, redirects, and restores
STDOUT and
STDERR:
#!/usr/bin/perl
open(OLDOUT, ">&STDOUT");
open(OLDERR, ">&STDERR");
open(STDOUT, ">foo.out") || die "Can't redirect stdout";
open(STDERR, ">&STDOUT") || 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
close(STDOUT);
close(STDERR);
open(STDOUT, ">&OLDOUT");
open(STDERR, ">&OLDERR");
print STDOUT "stdout 2\n";
print STDERR "stderr 2\n";
If you specify '<&=N', where N is a number, then Perl will do an equivalent of C's fdopen() of that file descriptor; this is more parsimonious of file descriptors. For
example:
open(FILEHANDLE, "<&=$fd")
If you open a pipe on the command '-', i.e., either '|-' or '-|', then there is an implicit fork done, and the return value of open is the
pid of the child within the parent process, and 0 within the child process. (Use defined($pid) to determine whether the open was successful.) 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 or
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 you are running setuid, and don't want to have to scan shell commands for metacharacters. The following pairs are more or less equivalent:
open(FOO, "|tr '[a-z]' '[A-Z]'");
open(FOO, "|-") || exec 'tr', '[a-z]', '[A-Z]';
open(FOO, "cat -n '$file'|");
open(FOO, "-|") || exec 'cat', '-n', $file;
See Safe Pipe Opens for more examples of this.
NOTE: On any operation that may do a fork, any
unflushed buffers remain unflushed in both processes, which means you may
need to set $| to avoid duplicate output.
Closing any piped filehandle causes the parent process to wait for the
child to finish, and returns the status value in $?.
The filename passed to open will have leading and trailing whitespace deleted, and the normal redirection characters honored. This property, known as ``magic open'', can often be used to good effect. A user could specify a filename of "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: $!";
However, to open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
If you want a ``real''
C open() (see open(2) on your system), then you should use the sysopen() function, which involves no such magic. 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 IO::Handle package (or one of its subclasses, such as IO::File or IO::Socket), you can generate anonymous filehandles that have the scope of whatever
variables hold references to them, and automatically close whenever and
however you leave that scope:
use IO::File;
#...
sub read_myfile_munged {
my $ALL = shift;
my $handle = new IO::File;
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.
$first; # Or here.
}
See seek() for some details about mixing reading and writing.
If rather than formatting bugs, you encounter substantive content errors in these documents, such as mistakes in the explanations or code, please use the perlbug utility included with the Perl distribution.