IO::Dir(3perl)

💖 IO::Dir 💖

okay bestie, welcome to IO::Dir — the perl manual page (yes, from the Perl Programmers Reference Guide, she's fancy) that gives you object methods for directory handles. literally so iconic of her. 🎀

✨ NAME ✨

IO::Dir — supply object methods for directory handles 💅

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe in code form, no edits, no nada:

use IO::Dir;
my $d = IO::Dir->new(".");
if (defined $d) {
    while (defined($_ = $d->read)) { something($_); }
    $d->rewind;
    while (defined($_ = $d->read)) { something_else($_); }
    undef $d;
}

tie my %dir, 'IO::Dir', ".";
foreach (keys %dir) {
    print $_, " " , $dir{$_}->size,"\n";
}

see how she just works? main character energy fr fr 🦋

---

🫶 DESCRIPTION 🫶

so IO::Dir gives you two interfaces to perl's directory reading routines. two! like she's got range. 👑

The first interface is an object approach. IO::Dir hands you an object constructor and a bunch of methods, and those methods are literally just wrappers around perl's built in directory reading routines. cozy, right?

new ( [ DIRNAME ] )

new is THE constructor for IO::Dir objects. she accepts one optional argument which, if given, new will pass to open. that's it that's the whole thing. optional queen. ✨

the methods 🎀

the following methods are wrappers for the directory related functions built into perl — and heads up, the trailing 'dir' has been removed from the names. so like, the naming got a little glow-up. 💅

go check perlfunc for the details on these functions, mwah:

• open ( DIRNAME )
• read ()
• seek ( POS )
• tell ()
• rewind ()
• close ()

the tied hash interface 🌈

IO::Dir also provides an interface to reading directories via a tied hash. and the tied hash extends the interface beyond just the directory reading routines, bestie — it pulls in lstat from the File::stat package, plus unlink, rmdir and utime. she's doing the most and we love her for it. 😭

tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]

okay so the keys of the hash? those will be the names of the entries in the directory. reading a value from the hash will be the result of calling File::stat::lstat.

deleting an element from the hash will delete the corresponding file or subdirectory — provided that DIR_UNLINK is included in the OPTIONS. don't forget that part, i'm begging. 🙈

assigning to an entry in the hash will cause the time stamps of the file to be modified. and if the file does not exist, then it will be created. new file, who dis? ✨

here's the tea on how you assign:

• assign a single integer to a hash element → both the access and modification times get changed to that value
• or pass a reference to an array of two values → the first array element sets the access time, and the second element sets the modification time

pick your fighter, both are valid. periodt. 💜

---

🧚 SEE ALSO 🧚

• File::stat

---

👑 AUTHOR 👑

Graham Barr. currently maintained by the Perl Porters. please report all bugs at [<https://github.com/Perl/perl5/issues>] — like actually report them, don't just complain in the group chat. 🫶

---

💖 COPYRIGHT 💖

Copyright (c) 1997-2003 Graham Barr <gbarr@pobox.com>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie!! this absolute banger of a manpage is from perl v5.44.0, dated 2026-10-17 (yes she's dated, she's timeless, she's IO::Dir(3perl)). slay, mwah, bye!! 💅✨🦋🌸🎀