IO::Dir(3pm)

💖 IO::Dir — the manual page, but make it a group chat 💖

okay so bestie, this is IO::Dir(3pm), straight out of the Perl Programmers Reference Guide, and it's literally the cutest little wrapper for reading directories. two whole interfaces, no cap. let's get into it 🎀

---

✨ NAME ✨

IO::Dir — supplying object methods for directory handles 🦋

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready:

    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";
    }

like… she does objects and tied hashes?? main character energy fr 💅

---

🦋 DESCRIPTION 🦋

okay so the IO::Dir package gives you two interfaces to perl's directory reading routines. two! icons only.

💜 the object approach

the first interface is the object one. IO::Dir provides an object constructor plus methods, and those methods are basically just wrappers around perl's built-in directory reading routines. nothing sketchy, just a glow-up ✨

🌟 new ( [ DIRNAME ] )

new is the constructor for IO::Dir objects. it takes one optional argument, and if you actually give it one, new will pass it straight to open. that's it, that's the whole thing 🫶

🌟 the methods

the following methods are wrappers for the directory-related functions built right into perl (the trailing 'dir' has been removed from the names — that's the lil makeover). see perlfunc for the deets on these functions:

• open ( DIRNAME ) — opens a directory handle for DIRNAME
• read () — reads the next entry
• seek ( POS ) — jumps to position POS
• tell () — tells you where you're at
• rewind () — back to the start, bestie
• close () — closes it out

---

🎀 the tied-hash era

IO::Dir also gives you an interface for reading directories through a tied hash. and she doesn't stop at directory reading routines — the tied hash extends the interface using lstat (from the File::stat package), plus unlink, rmdir and utime. it's giving overachiever 💀✨

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

the keys of the hash? those are the names of the entries in the directory. iconic.

• reading a value from the hash gives you the result of calling File::stat::lstat 👑
• deleting an element from the hash deletes the corresponding file or subdirectory — only provided that DIR_UNLINK is included in the OPTIONS. so like, don't blame her if it didn't happen, check your OPTIONS 🙈

⚠️ lowkey important: no DIR_UNLINK in OPTIONS = no deletion. periodt.

⭐ assigning to entries (time stamp chaos)

assigning to an entry in the hash will modify the time stamps of the file. and if the file doesn't even exist? it gets created. she'll make it happen 💅

so here's the tea on how you set those times:

• assign a single integer to a hash element → both the access time and the modification time 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

two-arg era, we love to see it 🌈

---

🔥 SEE ALSO 🔥

File::stat — go read it, iykyk 📚

---

💖 AUTHOR 💖

Graham Barr. currently maintained by the Perl Porters. please report all bugs at <https://github.com/Perl/perl5/issues>. they wanna hear from you, bestie 🫶

---

🌸 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. iconic licensing behavior, no notes 💜

---

okay that's the whole page!! and before you close the tab — this lil masterpiece is perl v5.42.3, dated 2026-11-03, and it's IO::Dir(3pm). mwah, go read some directories 💋🎀🦋