SCANDIR(3)

✨ SCANDIR(3) ✨

okay so bestie, we're in section 3 of the Library Functions Manual today, which means we're hanging out in the Standard C Library (libc, -lc) and we're gonna talk about scanning directories. yes. that thing. it's giving "the most useful thing you'll ever do with a directory" and it lowkey slays 💅

---

🎀 NAME 🎀

scandir, fdscandir, scandirat, scandir_b, fdscandir_b, fdscandirat_b, alphasort, versionsort — scan a directory 💖

(and yes, fdscandirat_b really is in the NAME list even though the rest of the page only ever talks about scandirat_b, iykyk — I'm not the one who wrote the header, I'm just the one telling you about it 🫶)

---

🌸 LIBRARY 🌸

Standard C Library (libc, -lc)

---

🦋 SYNOPSIS 🦋

okay bestie, get your #include ready:

#include <dirent.h>

then, the icons themselves:

int
scandir(const char *dirname, struct dirent ***namelist,
    int (*select)(const struct dirent *),
    int (*compar)(const struct dirent **, const struct dirent **));

int
fdscandir(int dirfd, struct dirent ***namelist,
    int (*select)(const struct dirent *),
    int (*compar)(const struct dirent **, const struct dirent **));

int
scandirat(int dirfd, const char *dirname, struct dirent ***namelist,
    int (*select)(const struct dirent *),
    int (*compar)(const struct dirent **, const struct dirent **));

int
scandir_b(const char *dirname, struct dirent ***namelist,
    int (^select)(const struct dirent *),
    int (^compar)(const struct dirent **, const struct dirent **));

int
fdscandir_b(int dirfd, struct dirent ***namelist,
    int (^select)(const struct dirent *),
    int (^compar)(const struct dirent **, const struct dirent **));

int
scandirat_b(int dirfd, const char *dirname, struct dirent ***namelist,
    int (^select)(const struct dirent *),
    int (^compar)(const struct dirent **, const struct dirent **));

int
alphasort(const struct dirent **d1, const struct dirent **d2);

int
versionsort(const struct dirent **d1, const struct dirent **d2);

notice the ^ blocks on the _b ones? that's the whole vibe. block energy 🔥

---

💖 DESCRIPTION 💖

the main character: scandir() 👑

So scandir() reads the directory dirname and builds up an array of pointers to directory entries, using malloc(3). it hands you back the number of entries in the array. and the pointer to that array of directory entries? it gets stored in the location referenced by namelist — even if no entries were selected. yes, even then. it's still there for you, bestie 🫶

select — the vibe check 🧚

The select argument is a pointer to a user-supplied subroutine that scandir() calls to decide which entries make the cut for the array. select gets handed a pointer to a directory entry, and it should return a non-zero value if that entry should be included. if select is null? all the entries get in. everyone's invited, no bouncer 🌈

compar — the sorting agenda 💅

The compar argument is a pointer to a user-supplied subroutine that gets passed to qsort(3) to sort the finished array. if this pointer is null, the array is just not sorted. chaos. we love her 🌸

the two ready-made comparators ⭐

• alphasort() — a routine you can totally use as the compar argument. it sorts the array alphabetically using strcoll(3).
• versionsort() — a routine you can also use as the compar argument. it sorts the array naturally using strverscmp(3). so file2 actually comes before file10, the way nature intended 😭

cleanup time 🧹

the memory allocated for the array can be deallocated with free(3) — you free each pointer in the array first, and then the array itself. order matters, bestie. don't skip leg day, don't skip the inner frees.

the fd variants 🦋

fdscandir() is basically scandir() but it takes a file descriptor that references a directory instead of a path. one thing though, no cap: the file descriptor is left open on return, regardless of outcome. even if things went sideways, it's still open. so that's on you to handle 👀

scandirat() is scandir()'s sibling with an extra dirfd argument. here's the breakdown:

• if the dirname you supplied is absolute, it behaves identically to scandir() and the dirfd argument is just... unused. sitting there. vibing. 🙈
• if dirname is relative, then dirfd has to be a valid file descriptor referencing a directory, and the dirname lookup happens relative to the directory that dirfd points at.
• if dirfd has the special value AT_FDCWD, then the current process directory is used as the base for relative lookups.
• and for all the extra details, go see openat(2). 📚

the _b girlies 🎀

scandir_b(), fdscandir_b(), and scandirat_b() behave exactly the same way as scandir(), fdscandir(), and scandirat() respectively — except they take blocks as arguments instead of function pointers, and they call qsort_b() rather than qsort(). that's the entire difference. slay. 🔥

---

👑 DIAGNOSTICS 👑

so scandir(), fdscandir(), scandirat(), scandir_b(), fdscandir_b(), and scandirat_b() all return the number of directory entries found on success. 💖

but if:

• the directory can't be opened for reading, or
• an error happens while reading the directory, or
• malloc(3) can't allocate enough memory to hold all the directory entries,

then they return -1 and set errno to an appropriate value. 😭 it's giving "it's not me, it's errno".

---

💀 ERRORS 💀

• scandir(), scandirat(), scandir_b(), and scandirat_b() may fail and set errno for any of the errors specified for the opendir(3), malloc(3), readdir(3), and closedir(3) functions.
• fdscandir() and fdscandir_b() may fail and set errno for any of the errors specified for the fdopendir(3), malloc(3), readdir(3), and closedir(3) functions.

(spot the difference: opendir(3) vs fdopendir(3). that's it. that's the whole switch-up 🫶)

---

🌈 SEE ALSO 🌈

openat(2), directory(3), malloc(3), qsort(3), strcoll(3), strverscmp(3), dir(5)

go read them. or don't. but like, they're right there 💜

---

🍓 STANDARDS 🍓

• alphasort() and scandir() are expected to conform to IEEE Std 1003.1-2008 (“POSIX.1”). iconic, certified, periodt ✅
• scandirat() and versionsort() are GNU extensions and conform to no standard. they're doing their own thing, no rules, main character energy 💅
• fdscandir(), scandir_b(), fdscandir_b(), and scandirat_b() are FreeBSD extensions. 🦋

---

🧚 HISTORY 🧚

• scandir() and alphasort() appeared in 4.2BSD. the elders. the originals. 👑
• scandir_b() was added in FreeBSD 11.0.
• scandirat() and versionsort() were added in FreeBSD 13.2.
• fdscandir(), fdscandir_b(), and scandirat_b() were added in FreeBSD 15.0. the babies of the family 🍓

---

okay that's the whole page bestie, go forth and scandir() responsibly 💖✨🎀

this edition came to you from Debian, dated June 25, 2025, and that's the SCANDIR(3) sign-off — mwah 💋