MAN page from Old RedHat 5.X perl-5.004-4.i386.rpm

FileHandle

Section: Perl Programmers Reference Guide (3)
Updated: perl 5.004, patch 04
Index

NAME

FileHandle - supply object methods for filehandles

SYNOPSIS

    use FileHandle;

    $fh = new FileHandle;    if ($fh->open "< file") {        print <$fh>;        $fh->close;    }

    $fh = new FileHandle "> FOO";    if (defined $fh) {        print $fh "bar\n";        $fh->close;    }

    $fh = new FileHandle "file", "r";    if (defined $fh) {        print <$fh>;        undef $fh;       # automatically closes the file    }

    $fh = new FileHandle "file", O_WRONLY|O_APPEND;    if (defined $fh) {        print $fh "corge\n";        undef $fh;       # automatically closes the file    }

    $pos = $fh->getpos;    $fh->setpos($pos);

    $fh->setvbuf($buffer_var, _IOLBF, 1024);

    ($readfh, $writefh) = FileHandle::pipe;

    autoflush STDOUT 1;

DESCRIPTION

NOTE: This class is now a front-end to the IO::* classes.

FileHandle::new creates a FileHandle, which is a reference to anewly created symbol (see the Symbol package). If it receives anyparameters, they are passed to FileHandle::open; if the open fails,the FileHandle object is destroyed. Otherwise, it is returned tothe caller.

FileHandle::new_from_fd creates a FileHandle like new does.It requires two parameters, which are passed to FileHandle::fdopen;if the fdopen fails, the FileHandle object is destroyed.Otherwise, it is returned to the caller.

FileHandle::open accepts one parameter or two. With one parameter,it is just a front end for the built-in open function. With twoparameters, the first parameter is a filename that may includewhitespace or other special characters, and the second parameter isthe open mode, optionally followed by a file permission value.

If FileHandle::open receives a Perl mode string (">'', ``+<'', etc.)or a POSIX fopen() mode string ("w'', ``r+'', etc.), it uses the basicPerl open operator.

If FileHandle::open is given a numeric mode, it passes that modeand the optional permissions value to the Perl sysopen operator.For convenience, FileHandle::import tries to import the O_XXXconstants from the Fcntl module. If dynamic loading is not available,this may fail, but the rest of FileHandle will still work.

FileHandle::fdopen is like open except that its first parameteris not a filename but rather a file handle name, a FileHandle object,or a file descriptor number.

If the C functions fgetpos() and fsetpos() are available, thenFileHandle::getpos returns an opaque value that represents thecurrent position of the FileHandle, and FileHandle::setpos usesthat value to return to a previously visited position.

If the C function setvbuf() is available, then FileHandle::setvbufsets the buffering policy for the FileHandle. The calling sequencefor the Perl function is the same as its C counterpart, including themacros _IOFBF, _IOLBF, and _IONBF, except that the bufferparameter specifies a scalar variable to use as a buffer. WARNING: Avariable used as a buffer by FileHandle::setvbuf must not bemodified in any way until the FileHandle is closed or untilFileHandle::setvbuf is called again, or memory corruption mayresult!

See the perlfunc manpage for complete descriptions of each of the followingsupported FileHandle methods, which are just front ends for thecorresponding built-in functions:

    close    fileno    getc    gets    eof    clearerr    seek    tell

See the perlvar manpage for complete descriptions of each of the followingsupported FileHandle methods:

    autoflush    output_field_separator    output_record_separator    input_record_separator    input_line_number    format_page_number    format_lines_per_page    format_lines_left    format_name    format_top_name    format_line_break_characters    format_formfeed

Furthermore, for doing normal I/O you might need these:

$fh->print: See the print entry in the perlfunc manpage.
$fh->printf: See the printf entry in the perlfunc manpage.
$fh->getline: This works like <$fh> described in the section on I/O Operators in the perlop manpageexcept that it's more readable and can be safely called in anarray context but still returns just one line.
$fh->getlines: This works like <$fh> when called in an array context toread all the remaining lines in a file, except that it's more readable.It will also croak() if accidentally called in a scalar context.

This document was created byman2html,using the manual pages.

FileHandle

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

Index