IO::Async::File(3pm)

💖 IO::Async::File 💖

okay bestie, this is the manual page for IO::Async::File(3pm) from the User Contributed Perl Documentation — and no, it's not boring, it's lowkey iconic. let's get into it 🫶

---

✨ NAME ✨

IO::Async::File — watch a file for changes 👀 (that's literally the whole job, and it slays)

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste it and go:

use IO::Async::File;

use IO::Async::Loop;
my $loop = IO::Async::Loop->new;

my $file = IO::Async::File->new(
   filename => "config.ini",
   on_mtime_changed => sub {
      my ( $self ) = @_;
      print STDERR "Config file has changed\n";
      reload_config( $self->handle );
   }
);

$loop->add( $file );

$loop->run;

---

🦋 DESCRIPTION 🦋

so this is a subclass of IO::Async::Notifier, right? and what it does is watch an open filehandle — or a named filesystem entity — for changes in its stat() fields. when those fields change value, it fires off various events. the most common use case is watching a file for size changes; if that's your goal, also go look at IO::Async::FileStream.

and the way it's called "File" but does NOT require the watched filehandle to be a regular file? yeah. you can watch literally anything stat(2) can be called on — directories, other filesystem entities, whatever. main character energy, it does not gatekeep 🎀

since version 0.805, a named file does not necessarily need to exist. if it's not there, all its stat() fields are treated as undefined; events get invoked when it becomes present or gets removed, plus whenever anything else changes. so it's tracking the whole arc, not just the glow-up 😭

---

🔥 EVENTS 🔥

these events get invoked, either using subclass methods or CODE references in parameters. yes, both. flexible queen.

💫 on_dev_changed $new_dev, $old_dev

💫 on_ino_changed $new_ino, $old_ino

💫 ...

💫 on_ctime_changed $new_ctime, $old_ctime

Invoked when each of the individual stat() fields have changed. all the stat() fields are supported apart from blocks and blksize — those two are the ones that didn't make the cut, sorry to them. each event is passed the new and old values of the field. either field may be undef if the file did not exist or currently does not exist (it's giving absent, but emotionally).

💫 on_devino_changed $new_stat, $old_stat

Invoked when either of the dev or ino fields have changed. it gets passed two File::stat instances containing the complete old and new stat() fields. bestie, this is the one you use to observe when a named file gets renamed — but heads up, that will not be observed to happen on opened filehandles. it's giving "only for the named files, periodt" 💅

💫 on_stat_changed $new_stat, $old_stat

Invoked when any of the stat() fields have changed. it gets passed two File::stat instances containing the old and new stat() fields. either value may be undef if the file did not exist or currently does not exist. this is the catch-all, the main event, the one that watches everything 🌈

---

💅 PARAMETERS 💅

these named parameters can be passed to new or configure. mix and match, do your thing ✨

• handle => IO — the opened filehandle to watch for stat() changes, if filename is not supplied.
• filename => STRING — Optional. if you supply it, it watches the named file rather than the filehandle given in handle. the file gets opened for reading and then watched for renames. if the file is renamed, the new filename is opened and tracked similarly, after closing the previous file. glow-up with a handle swap, we love to see it 🦋
• interval => NUM — Optional. the interval in seconds to poll the filehandle using stat(2) looking for size changes. if you don't define it, a default of 2 seconds gets applied. no cap, just twice-a-second-ish energy ⏱️

---

👑 METHODS 👑

⭐ handle

$handle = $file->handle;

Returns the filehandle currently associated with the instance; either the one passed to the handle parameter, or opened from the filename parameter. either way, it's your handle, owned and iconic.

---

💜 AUTHOR 💜

Paul Evans <leonerd@leonerd.org.uk>

---

that's the whole page bestie, you've officially read the entire manual 💖 no cap. this was perl v5.40.1, dated 2026-02-21, IO::Async::File(3pm) — and yes, the footer is the sign-off, so: mwah, bye, go watch some files 🎀💅🫶