FileHandle(3perl)

💖 NAME 💖

FileHandle — bestie, it supplies object methods for filehandles 🎀

---

✨ SYNOPSIS ✨

use FileHandle;

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

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

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

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

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

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

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

autoflush STDOUT 1;

---

🌸 DESCRIPTION 🌸

NOTE: this class is now a front-end to the IO::* classes. So it's giving OG vibes but the actual work is happening behind the scenes 💅

FileHandle::new creates a FileHandle, which is a reference to a newly created symbol (see the Symbol package, iykyk). If it receives any parameters, those get passed straight to FileHandle::open. And if the open fails? The FileHandle object gets destroyed 💀. Otherwise it's returned to the caller, like, "here u go bestie".

FileHandle::new_from_fd creates a FileHandle the same way new does. It requires two parameters, and those get passed to FileHandle::fdopen. If the fdopen fails, the FileHandle object is destroyed (rip 🙈). Otherwise it's returned to the caller.

FileHandle::open accepts one parameter or two. With one parameter it's just a front end for the built-in open function, no extra drama. With two parameters, the first one is a filename that's allowed to include whitespace or other special characters (iconic, honestly), and the second is the open mode, optionally followed by a file permission value.

If FileHandle::open gets a Perl mode string (">", "+<", etc.) or a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic Perl open operator. Simple as that ✨

If FileHandle::open is handed a numeric mode, it passes that mode and the optional permissions value to the Perl sysopen operator. And for convenience, FileHandle::import tries to import the O_XXX constants from the Fcntl module. If dynamic loading isn't available this may fail, but don't panic — the rest of FileHandle still works fine 🫶

FileHandle::fdopen is like open except its first parameter isn't a filename, bestie, it's a file handle name, a FileHandle object, or a file descriptor number. Different flavor, same energy.

If the C functions fgetpos() and fsetpos() are available, then FileHandle::getpos returns an opaque value representing the current position of the FileHandle, and FileHandle::setpos uses that value to go back to a position you've visited before. Time travel but make it I/O 🦋

If the C function setvbuf() is available, then FileHandle::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 the buffer parameter specifies a scalar variable to use as a buffer.

⚠️ WARNING: a variable used as a buffer by FileHandle::setvbuf must not be modified in any way until the FileHandle is closed or until FileHandle::setvbuf is called again — or memory corruption may result! Like, do NOT touch it. Fr fr. 💀

See perlfunc for complete descriptions of each of the following supported FileHandle methods, which are literally just front ends for the corresponding built-in functions:

close
fileno
getc
gets
eof
clearerr
seek
tell

See perlvar for complete descriptions of each of the following supported 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

And furthermore, for doing normal I/O you might need these 👇

• $fh->print — see "print" in perlfunc.
• $fh->printf — see "printf" in perlfunc.
• $fh->getline — this works like <$fh> described in "I/O Operators" in perlop, except that it's more readable and can be safely called in a list context but still returns just one line. One line only, bestie, don't get greedy 💅
• $fh->getlines — this works like <$fh> when called in a list context to read all the remaining lines in a file, except that again it's more readable. It will also croak() if you accidentally call it in a scalar context — so watch out for that 😭

There are many other functions available since FileHandle is descended from IO::File, IO::Seekable, and IO::Handle. Please see those respective pages for documentation on more functions — the lore goes deep, go read them 🧚

---

👑 SEE ALSO 👑

The IO extension, perlfunc, "I/O Operators" in perlop.

---

That's the whole page, bestie! 🫶 This one came from perl v5.44.0, dated 2026-10-17, and it lives in the Perl Programmers Reference Guide as FileHandle(3perl). Slay, go close your filehandles. Periodt. 💖