|
open - open a file, pipe, or descriptor |
open - open a file, pipe, or descriptor
open FILEHANDLE,MODE,LIST
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. (This is considered a symbolic reference, so use
strict 'refs' should not be in effect.)
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.) See the
perlopentut manpage for a kinder, gentler explanation of opening files.
If MODE is '<' or nothing, the file is
opened for input. If MODE is '>', the file
is truncated and opened for output, being created if necessary. If MODE is '>>', 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 file is created with permissions
of 0666 modified by the process' umask value.
These various prefixes correspond to the fopen(3) modes of
'r', 'r+', 'w', 'w+',
'a', and 'a+'.
In the 2-arguments (and 1-argument) form of the call the mode and filename
should be concatenated (in this order), possibly separated by spaces. It is
possible to omit the mode if the mode is '<'.
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 as a command which pipes output to
us. See Using
open() for IPC in the perlipc manpage for more examples
of this. (You are not allowed to open to a command that pipes both
in and out, but see the
IPC::Open2 manpage, the
IPC::Open3 manpage, and Bidirectional
Communication with Another Process in the perlipc manpage for
alternatives.)
If MODE is '|-', the filename is
interpreted as a command to which output is to be piped, and if MODE is '-|', the filename is interpreted as a
command which pipes output to us. In the 2-arguments (and 1-argument) form one
should replace dash ('-') with the command. See Using
open() for IPC in the perlipc manpage for more examples
of this. (You are not allowed to open to a command that pipes both
in and out, but see the
IPC::Open2 manpage, the
IPC::Open3 manpage, and Bidirectional
Communication in the perlipc manpage for alternatives.)
In the 2-arguments (and 1-argument) form 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
in the perlfunc manpage 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(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/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.) Duping file
handles is not yet supported for 3-argument open().
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")
Note that this feature depends on the fdopen() C library function. On many UNIX systems,
fdopen() is known to fail when file descriptors exceed a certain
value, typically 255. If you need more file descriptors than that, consider
rebuilding Perl to use the sfio library.
If you open a pipe on the command '-', i.e., either
'|-' or '-|' with 2-arguments (or 1-argument) form of
open(), 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 triples 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, "cat -n '$file'|");
open(FOO, '-|', "cat -n '$file'");
open(FOO, '-|') || exec 'cat', '-n', $file;
See Safe Pipe Opens in the perlipc manpage 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 the
perlport manpage). To be safe, you may need to set $|
($AUTOFLUSH in English) or call the autoflush()
method of 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 $^F. See $^F in the perlvar manpage.
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 2-argument (or 1-argument) form of 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: $!";
Use 3-argument form to open a file with arbitrary weird characters in it,
open(FOO, '<', $file);
otherwise it's necessary to protect any leading and trailing whitespace:
$file =~ s#^(\s)#./$1#;
open(FOO, "< $file\0");
(this may not work on some bizarre filesystems). One should conscientiously choose between the magic and 3-arguments form of open():
open IN, $ARGV[0];
will allow the user to specify an argument of the form "rsh cat file
|", but will not work on a filename which happens to have a trailing
space, while
open IN, '<', $ARGV[0];
will have exactly the opposite restrictions.
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 (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 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 in the perlfunc manpage for some details about mixing reading and writing.
|
open - open a file, pipe, or descriptor |