Dirent(3pm)

💖 NAME 💖

IO::Dirent — bestie, it's your all-access pass to the dirent structs that readdir hands back ✨ (literally the raw deets on every file in a directory, served fresh)

---

🌸 SYNOPSIS 🌸

  use IO::Dirent;

  ## slurp-style
  opendir DIR, "/usr/local/foo";
  my @entries = readdirent(DIR);
  closedir DIR;

  print $entries[0]->{name}, "\n";
  print $entries[0]->{type}, "\n";
  print $entries[0]->{inode}, "\n";

  ## using the enumerator
  opendir DIR, "/etc";
  while( my $entry = nextdirent(DIR) ) {
    print $entry->{name} . "\n";
  }
  closedir DIR;

---

✨ DESCRIPTION ✨

Okay so, two whole moods here. Pick your fighter 💅

readdirent hands you back a list of hashrefs. Every single hashref is packing:

• the name of the directory entry 👑
• its inode for the filesystem it lives on
• its type (if it's available)

Important tea: if the file type or the inode is not available, it just won't be there. No fake keys, no empty strings pretending to be data. It's giving honesty. 🫶

nextdirent returns the next dirent as a hashref, which lets you walk through directory entries one by one instead of grabbing the whole list. Lowkey perfect when you're low on memory, or when the directory is absolutely enormous and you don't wanna yeet your RAM into the void 😭

🎀 What gets exported

IO::Dirent exports these symbols by default:

  readdirent

  nextdirent

And these tags may be exported to your namespace if you ask nicely:

  ALL

ALL is the whole bundle 💖 — it includes readdirent, nextdirent, and also these lil constants:

  DT_UNKNOWN
  DT_FIFO
  DT_CHR
  DT_DIR
  DT_BLK
  DT_REG
  DT_LNK
  DT_SOCK
  DT_WHT

🦋 Testing file types

You can use those constants to vibe-check the file type that readdirent gave you, like this:

  for my $entry ( readdirent(DIR) ) {
      next unless $entry->{'type'} == DT_LNK;

      print $entry->{'name'} . " is a symbolic link.\n";
  }

🙈 When your platform is not like other platforms

For platforms that do not implement file type inside their dirent struct, readdirent will return a hashref with a single key/value of 'name' and the filename — which is effectively the same as plain readdir. And yeah, this is subject to change, if the author can implement some of the to do items below. So like, watch this space 👀

---

💀 CAVEATS 💀

Real talk. This was written on FreeBSD and OS X, which implement a robust (but somewhat non-standard) dirent struct — and that struct includes a file type entry. Gorgeous. Iconic.

The author has plans to make this module more portable and more useful by doing a stat on each directory entry to find the file type and inode number, for when dirent.h does not implement it otherwise.

Improvements and additional ports are welcome 🫶 come thru.

---

👑 TO DO 👑

1. For platforms that do not implement a dirent struct with file type, do a stat on the entry and populate the structure anyway. (Manifesting this one fr fr 🙏)
2. Do some memory profiling (the author isn't sure if there are any leaks or not). Not me side-eyeing the malloc 💀

---

💜 COPYRIGHT 💜

Copyright 2002, 2011 Scott Wiersdorf.

This library is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License.

---

🌈 AUTHOR 🌈

Scott Wiersdorf, <scott@perlcode.org>

---

🧚 ACKNOWLEDGEMENTS 🧚

Thanks to Nick Ing-Simmons for his help on the perl-xs mailing list. The way that mailing list came through for him 🙌

---

⭐ SEE ALSO ⭐

dirent(5), perlxstut, perlxs, perlguts, perlapi

---

🍓 COPYRIGHT AND LICENSE 🍓

Copyright (C) 2007 by Scott Wiersdorf

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

---

And that's the whole page, bestie 💖 this one's from perl v5.42.3 and it was dated 2026-08-20 when it landed in the Dirent(3pm) spot. Go read some directories, you main character 👑✨