7.2.33 FileHandle - Supply Object Methods for Filehandles

use FileHandle;

$fh = new FileHandle;
if ($fh->open "< 

file

") {
    print <$fh>;
    $fh->close;
}

$fh = new FileHandle "> 

file

";
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 "stuff\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;

new

Creates a FileHandle, which is a reference to a newly created symbol (see the Symbol library module). If it receives any parameters, they are passed to open() . If the open fails, the FileHandle object is destroyed. Otherwise, it is returned to the caller.

new_from_fd

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

open

Accepts one parameter or two. With one parameter, it is just a front end for the built-in open function. With two parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode in either Perl form ( ">" , "+<" , and so on) or POSIX form ( "w" , "r+" , and so on).

fdopen

Like open() except that its first parameter is not a filename but rather a filehandle name, a FileHandle object, or a file descriptor number.

getpos

If the C functions fgetpos (3) and fsetpos (3) are available, then getpos() returns an opaque value that represents the current position of the FileHandle, and setpos() uses that value to return to a previously visited position.

setvbuf

If the C function setvbuf (3) is available, then setvbuf() sets the buffering policy for the FileHandle. The calling sequence for the Perl function is the same as its C counterpart, including the macros _IOFBF , _IOLBF , and _IONBF , except that the buffer parameter specifies a scalar variable to use as a buffer.

WARNING: A variable used as a buffer by setvbuf() must not be modified in any way until the FileHandle is closed or until setvbuf() is called again, or memory corruption may result!

The following supported FileHandle methods are just front ends for the corresponding built-in Perl functions:

clearerr	getc
close	gets
eof	seek
fileno	tell

The following supported FileHandle methods correspond to Perl special variables:

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

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

$fh->print

See Perl's built-in print function.

$fh->printf

See Perl's built-in printf function.

$fh->getline

This method works like Perl's <FILEHANDLE> construct, except that it can be safely called in an array context, where it still returns just one line.

$fh->getlines

This method works like Perl's <FILEHANDLE> construct when called in an array context to read all remaining lines in a file. It will also croak() if accidentally called in a scalar context.