FileHandle (Programming Perl)

32.26. FileHandle

use FileHandle;

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

$pos = $fh->getpos;     # like tell()
$fh->setpos($pos);      # like seek()

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

autoflush STDOUT 1;

The FileHandle module mostly serves as a mechanism for cloaking Perl's punctuation variables in longer, more OO-looking calls. It is provided for compatibility with older releases, but is now really only a frontend for several more specific modules, like IO::Handle and IO::File.[5] Its best property is the low-level access it provides to certain rare functions from the C library (clearerr(3), fgetpos(3), fsetpos(3), and setvbuf(3)).

[5]Because it loads so much code, this module costs you a megabyte or so of memory.

Variable	Method
`$\|`	`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`
`$^L`	`format_formfeed`

Instead of saying:

$ofh = select(HANDLE);
$~ = 'SomeFormat';
$| = 1;
select($ofh);

you can just say:

use FileHandle;
HANDLE->format_name('SomeFormat');
HANDLE->autoflush(1);

Currently, three methods (output_field_separator, output_record_separator, and input_record_separator) only pretend to be per-handle methods: setting them on one handle actually affects all filehandles. They are therefore only supported as class methods, not as per-filehandle methods. This restriction may be lifted someday.

To get a lexically scoped filehandle, instead of using filehandle autovivification:

open my $fh, "< somefile"
    or die "can't open somefile: $!";

one could say:

use FileHandle;
my $fh = FileHandle->new("< somefile")
    or die "can't open somefile: $!";

FileHandle inherits from IO::File, which inherits from IO::Handle and IO::Seekable. Virtually all the module's functionality is available more efficiently through basic, unadorned Perl calls, except for the following, not all of which may be implemented on all non-Unix platforms:

HANDLE->blocking(EXPR)

Called with an argument, enables nonblocking I/O if the argument is false, and disables nonblocking (that is, enables blocking) if the argument is true. The method returns the previously set value (which is still the current setting if no argument was given). On error, blocking sets $! and returns undef. This could be done using fcntl directly, but the FileHandle interface is much easier to use.

HANDLE->clearerr

Calls the C library function clearerr(3) to clear the handle's internal end-of-file and error status indicators.

HANDLE->error

Calls the C library function ferror(3) to test the error indicator for the given handle, returning whether that internal indicator is set. The error indicator can be reset reliably only via the clearerr method. (Some systems also reset it on calls to the seek operator.)

HANDLE->formline(PICTURE, LIST)

This is the same as saving the old accumulator variable ($^A), calling the formline function with the given PICTURE and LIST, outputting the resulting contents of the accumulator to the given handle, and finally restoring the original accumulator. For example, here's how to output a long text variable, with automatic word-wrapping at column 72:

use FileHandle;
STDOUT->formline("^" . ("<" x 72) . "~~\n", $long_text);

HANDLE->getpos

Calls the C library function fgetpos(3), providing an alternative interface to tell. On some (non-UNIX) systems the return value may be a complex object, and getpos and setpos may be the only way to portably reposition a text stream.

FileHandle->new_tmpfile

Calls the C library function tmpfile(3) to create a new temporary file opened for read-write mode and returns a handle to this stream. On systems where this is possible, the temporary file is anonymous--that is, it is unlinked after creation, but held open. You should use this function, or POSIX::tmpnam as described under the POSIX module, to safely create a temporary file without exposing yourself to subtle but serious security problems through race conditions. As of the 5.6.1 release of Perl, the File::Temp module is now the preferred interface.

HANDLE->setbuf(BUFFER)

Calls the C library function setbuf(3) with the given BUFFER variable. It passes undef to indicate unbuffered output. A variable used as a buffer by setbuf or setvbufmust not be modified in any way until the handle is closed, or until setbuf or setvbuf is called again. Otherwise, memory corruption may result, and you will be sad.

HANDLE->setpos(EXPR)

Calls the C library function fsetpos(3), providing an alternative interface to seek. The argument should only be the return value from getpos, described earlier.

HANDLE->setvbuf(BUFFER, TYPE, SIZE)

Calls the C library function setvbuf(3) with the given BUFFER. The standard C library constants _IONBF (unbuffered), _IOLBF (line buffered), and _IOFBF (fully buffered) are available for the TYPE field if explicitly imported. See the warning under setbuf.

HANDLE->sync

Calls the C library function fsync(3) to synchronize a file's in-memory state with the physical medium. Note that sync operates not on the handle, but on the file descriptor, so any data held by buffers will not be synchronized unless flushed first.

HANDLE->untaint

Marks the filehandle or directory handle as providing untainted data. When running under taint mode (see Chapter 23, "Security"), data read in from external files is considered untrustworthy. Do not invoke this method blindly: you're circumventing Perl's best attempts to protect you from yourself.