DirHandle(3perl)

💖 DirHandle — the manual, but make it group chat 💖

okay bestie, buckle up, because this is a Perl Programmers Reference Guide page and it's literally called DirHandle(3perl). yes, the 3perl bit means it's a library doc. no, it is not exciting. but we're gonna make it cute anyway 🎀

---

✨ NAME ✨

DirHandle — (obsolete) supply object methods for directory handles 💅

like... the module is right there in the name. it's a handle. for directories. object methods. that's the whole thing. and yes, "obsolete" is in the official description, not me being shady. 🫶

---

🌸 SYNOPSIS 🌸

first up, the version where you do the sensible thing:

    # recommended approach since Perl 5.6: do not use DirHandle
    if (opendir my $d, '.') {
        while (readdir $d) { something($_); }
        rewind $d;
        while (readdir $d) { something_else($_); }
    }

see how that comment says recommended? and how it says do not use DirHandle? yeah. that's the vibe. the module is so over it, the synopsis is telling you to go around it 😭

and then, for the historical record, the version where you were going to use it:

    # how you would use this module if you were going to
    use DirHandle;
    if (my $d = DirHandle->new(".")) {
        while (defined($_ = $d->read)) { something($_); }
        $d->rewind;
        while (defined($_ = $d->read)) { something_else($_); }
    }

both blocks do the same dance: read everything once, rewind, read it all again but with a different callback. peak rewind-and-reread behaviour. iconic, honestly. 🔥

---

🦋 DESCRIPTION 🦋

okay so, the first sentence. the actual first sentence of the actual description:

There is no reason to use this module nowadays.

no reason. none. zero. nada. the documentation itself is giving you the "just don't" talk. 💀

that said, here's what it was:

the DirHandle method provides an alternative interface to the opendir(), closedir(), readdir(), and rewinddir() functions. same four jobs, but wrapped up all object-y and method-call-y. you know the type. 👑

now for the lore. 🧚 back in the day — specifically up to Perl 5.5 — opendir() could not autovivify a directory handle from undef. so if you wanted a lexical handle, you had to go get a function from Symbol to create an anonymous glob, which was a whole separate step. annoying!! extra steps!! not the move.

DirHandle encapsulates all of that, which meant you could write cleaner code than plain opendir() allowed. it was genuinely the upgrade at the time, no cap. ⭐

but — and this is the plot twist — since Perl 5.6, opendir() alone has been all you need for lexical handles. the module's whole reason for existing got absorbed into the language itself. the student surpassed the teacher. the circle is complete. 🫶

so like: if you're writing new code, you don't need this. periodt. the core function ate. 💅

---

👑 SEE ALSO 👑

ngl, this page doesn't list any. no cross-references, no friends, no shoutouts. it's just opendir(), closedir(), readdir(), rewinddir() and the Symbol module mentioned up in the description, and that's the whole guest list. 🙈

---

and that's the page!! you made it!! 🎀 this was pulled from perl v5.44.0, dated 2026-10-17, and it lives under DirHandle(3perl) in the Perl Programmers Reference Guide. mwah, love u, go use opendir() directly 💜