FileHandle (Perl in a Nutshell, 2nd Edition)

8.112. FileHandle

new

$fh = new FileHandle [filename[, mode]]

Constructor. Creates a FileHandle, which is a reference to a newly created symbol. The optional parameters, filename and mode, are passed to open. The FileHandle object is returned if the open succeeds; otherwise, it is destroyed.

new_from_fd

$fh = new_from_fd FileHandle fd, mode

Constructor. Creates a FileHandle, but it takes the file descriptor, fd, instead of filename as a parameter, along with mode; the parameters are required.

fdopen

$fh->fdopen fdname [openmode]

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

getpos

$pos = $fh->getpos

If the C functions fgetpos(3) and fsetpos(3) are available, getpos returns the current position, $pos, of the FileHandle.

open

$fh->open filename [openmode]

Takes filename and, optionally, the open mode, and opens a file. If the mode is present, it can be in Perl form (e.g., >, +<) or in POSIX form (e.g., w, r+).

setpos

$fh->setpos pos

Uses the value (pos) returned by getpos to restore a previous position of the FileHandle.

setvbuf

$fh->setvbuf(params)

Takes the same parameters as the C function setvbuf(3) and uses the C function to set the buffering policy for the FileHandle.

The following additional FileHandle methods act as front-ends for the corresponding built-in Perl functions (see the O'Reilly book Programming Perl or the perlfunc manpage for more details):

`clearerr`	`getc`
`close`	`gets`
`eof`	`seek`
`fileno`	`tell`

The next group of FileHandle methods correspond to Perl special variables (see Programming Perl or the perlvar manpage):

`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`

Finally, the following methods are useful:

$fh->print: See Perl's built-in print function.
$fh->printf: See Perl's built-in printf function.
$fh->getline: Works like Perl's <FILEHANDLE> construct, except that it can be safely called in an array context (but it still returns just one line).
$fh->getlines: Works like Perl's <FILEHANDLE> construct when called in an array context to read all remaining lines in a file.