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)).
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) . "~~ ", $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 unlink
ed 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 setvbuf
must 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), 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.