NAME

SYNOPSIS

open FILEHANDLE

DESCRIPTION

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. If the filename begins with '>>', the file is opened for appending. 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. The prefix and the filename may be separated with spaces. These various prefixes correspond to the fopen 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. as command which pipes input to us. (You may not have a raw 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 non-zero 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 and Plan9 that delimit lines with a single character, and that encode that character in C as '\n', do not need binmode. The rest need it.

Examples:

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

    open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved)

    open(DBASE, '+<dbase.mine');	    # open for update

    open(ARTICLE, "caesar <$article |");    # decrypt article

    open(EXTRACT, "|sort >/tmp/Tmp$$");     # $$ is our process id

    # process argument list of files along with any includes

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

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

	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) which is 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(SAVEOUT, ">&STDOUT");
    open(SAVEERR, ">&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, ">&SAVEOUT");
    open(STDERR, ">&SAVEERR");

    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 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.

Explicitly closing any piped filehandle causes the parent process to wait for the child to finish, and returns the status value in $?. Note: on any operation which may do a fork, unflushed buffers remain unflushed in both processes, which means you may need to set $| to avoid duplicate output.

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 which 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.
    }

The filename that is passed to open will have leading and trailing whitespace deleted. To open a file with arbitrary weird characters in it, it's necessary to protect any leading and trailing whitespace thusly:

    $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. This is another way to protect your filenames from interpretation. For example:

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

See seek() for some details about mixing reading and writing.