PERLFUNC: open - open a file, pipe, or descriptor 
Author Message
 PERLFUNC: open - open a file, pipe, or descriptor

(This excerpt is from the perlfunc manpage, part of the standard set of
documentation included with every valid Perl distribution--like the one on
your own system.  See also http://www.*-*-*.com/
or http://www.*-*-*.com/
if your negligent system adminstrator has been remiss in his duties.)

NAME
    open - open a file, pipe, or descriptor

SYNOPSIS
    open FILEHANDLE,EXPR

    open FILEHANDLE

DESCRIPTION
    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.) See the perlopentut manpage for a
    kinder, gentler explanation of opening files.

    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 file is created with permissions
    of `0666' modified by the process' `umask' value.

    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 as a command which pipes
    output to us. See the section on "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 the section on
    "Bidirectional Communication" in the perlipc manpage 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 the "binmode" entry
    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(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


            process($file, 'fh00');
        }

        sub process {

            $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 the section on "Safe Pipe Opens" in the perlipc manpage 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. 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 the section on
    "$^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 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 the open(2) manpage 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 the "seek" entry in the perlfunc manpage for some details about
    mixing reading and writing.

--
keyboard not connected -- press F1 to continue



Fri, 02 Nov 2001 03:00:00 GMT  
 
 [ 1 post ] 

 Relevant Pages 

1. PERLFUNC: open - open a file, pipe, or descriptor

2. PERLFUNC: pipe - open a pair of connected filehandles

3. PERLFUNC: pipe - open a pair of connected filehandles

4. Perl's open() pukes when trying to open a read-type pipe

5. **URGENT** Finding the number of open file descriptors using perl

6. Using open() for IPC -- can't fork due to bad file descriptor

7. how to open file descriptor by number?

8. open() leaks file descriptors? (fwd)

9. managing open file descriptors w/ cacheout

10. Passing open file descriptor to an unrelated process

11. open FILE,$path || open FILE,$altpath;

12. Piping in stderr when creating a pipe with the open call

 

 
Powered by phpBB® Forum Software