IO::File(3perl)

💖 IO::File — the manual page, but make it cute 💖

okay bestie, gather round, because IO::File from the Perl Programmers Reference Guide is genuinely one of those little modules that just works and never asks for credit. she's giving quiet luxury, no cap. this is IO::File(3perl), and she's about to make your filehandles infinitely more slay than they were five minutes ago. 🎀

---

✨ NAME ✨

IO::File — supply object methods for filehandles. yes, object methods. for filehandles. we're living in the future, babe. 💅

---

🦋 SYNOPSIS 🦋

look at her. look at the range. 👑

use IO::File;

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

my $fh = IO::File->new("> file");
if (defined $fh) {
    print $fh "bar\n";
    $fh->close;
}

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

my $fh = IO::File->new("file", O_WRONLY|O_APPEND);
if (defined $fh) {
    print $fh "corge\n";

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

    undef $fh;       # automatically closes the file
}

autoflush STDOUT 1;

not me just reading this and feeling something. 😭 the undef $fh closing the file automatically? the way that's so giving garbage collection but chiller? obsessed.

---

🌸 DESCRIPTION 🌸

so here's the tea, bestie: IO::File inherits from IO::Handle and IO::Seekable. 🫶 it takes everything those two iconic queens already do and it extends them — with methods that are specific to file handles. that's it. that's the whole pitch. she's not reinventing the wheel, she's just putting a cuter rim on it. ✨

---

🎀 CONSTRUCTOR 🎀

new ( FILENAME [,MODE [,PERMS]] )

creates an IO::File. 💖

and like, if it receives any parameters at all, those parameters get passed straight to the method open. if the open fails? the object is destroyed. poof. gone. she said "no thank you" and vanished. 🫠 but if it doesn't fail, the object is returned to the caller, and you get to live your main character life.

new_tmpfile

creates an IO::File that's opened for read/write on a newly created temporary file. 🧚

on systems where this is possible, that temporary file is anonymous — meaning it gets unlinked right after creation but stays held open. it's giving stealth mode. it's giving no name, no trace, only vibes. 🌈

and if the temporary file can't be created or opened? the IO::File object gets destroyed. otherwise it comes back to you, ready to be used. no cap.

---

💅 METHODS 💅

open( FILENAME [,MODE [,PERMS]] )

open( FILENAME, IOLAYERS )

okay so open is flexible and honestly kind of a diva about it — she accepts one, two, or three parameters:

• with one parameter, she's just a front end for the built-in open function. simple. lowkey. doing the bare minimum beautifully. ✨
• with two or three parameters, the first parameter is a filename that may include whitespace or other special characters, and the second parameter is the open mode — optionally followed by a file permission value. 🔥

now here's the part you need to remember for the quiz, bestie:

• if IO::File::open receives a Perl mode string (">", "+<", etc.) or an ANSI C fopen() mode string ("w", "r+", etc.), it uses the basic Perl open operator — but it protects any special characters. safety first, always. 🛡️
• if IO::File::open is given a numeric mode, it passes that mode plus the optional permissions value to the Perl sysopen operator. and the permissions default to 0666. write that down. 0666. 💀
• if IO::File::open is given a mode that includes the ":" character, it passes all three arguments to the three-argument open operator. all three. she's not leaving anybody behind.

and for convenience — because she's thoughtful like that — IO::File exports the O_XXX constants from the Fcntl module, if this module is available. 🌟

---

🙈 NOTE 🙈

okay so this part is important and I need you to actually listen:

some operating systems may perform IO::File::new() or IO::File::open() on a directory without errors. 😭 this behavior is not portable and not suggested for use. like, she can do it, but she shouldn't, and you definitely shouldn't make her.

using opendir() and readdir() or IO::Dir is suggested instead. do that. please. for me. 🫶

---

⭐ SEE ALSO ⭐

• perlfunc
• "I/O Operators" in perlop
• IO::Handle
• IO::Seekable
• IO::Dir

go read them, bestie. knowledge is the accessory that never goes out of style. 💜

---

👑 HISTORY 👑

derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>. we stan a legend. thank you for your service, Graham. 🫡🌸

---

and that's the whole page, babes. this documentation came to you from perl v5.44.0, dated 2026-10-17, and honestly? she ate. 💖 ✨ 🎀 go open a file. you got this. slay. 🦋