GETDIRENTRIES(2)

💅 GETDIRENTRIES(2) — ok so this is a System Calls Manual page, section 2, bestie 🎀

✨ NAME ✨

getdirentries, getdents — the girlies that get you directory entries in a file system independent format 🗂️✨

---

🫶 LIBRARY 🫶

Standard C Library (libc, -lc) — she lives in libc, no cap.

---

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <dirent.h>

ssize_t
getdirentries(int fd, char *buf, size_t nbytes, off_t *basep);

ssize_t
getdents(int fd, char *buf, size_t nbytes);

---

💖 DESCRIPTION 💖

Okay so picture this: the getdirentries() and getdents() system calls read directory entries from the directory that fd points at, and dump them into the buffer pointed to by buf, in a file system independent format. Iconic behaviour honestly. Up to nbytes of data gets transferred. ✨

Watch out though — nbytes has to be greater than or equal to the block size associated with the file (peep stat(2) for that). Some file systems lowkey may not support these system calls at all if your buffer is smaller than that size, so like… don't play with it. 🙈

The data in the buffer is a whole series of dirent structures, each one containing these entries:

ino_t     d_fileno;
off_t     d_off;
uint16_t  d_reclen;
uint8_t   d_type;
uint16_t  d_namlen;
char      d_name[MAXNAMLEN + 1];        /* see below */

Let's break down the cast, because each field is a main character 🎬:

• d_fileno — a number that's unique for each distinct file in the file system. Files linked by hard links (see link(2)) share the same d_fileno. Sibling energy fr fr.
• d_off — returns a cookie which, if non-zero, can be used with lseek(2) to position the directory descriptor to the next entry. 🍪
• d_reclen — the length, in bytes, of the directory record.
• d_type — the type of the file pointed to by the directory record. The file type values are defined in <sys/dirent.h>.
• d_name — contains a null terminated file name.
• d_namlen — specifies the length of the file name excluding the null byte. So the actual size of d_name may vary from 1 to MAXNAMLEN + 1. She's flexible 💅.

Entries may be separated by extra space — don't freak out. You can use the d_reclen entry as an offset from the start of a dirent structure to the next structure, if any exists. 🦋

The actual number of bytes transferred is what gets returned. The current position pointer associated with fd is set to point to the next block of entries. But heads up: the pointer may not advance by the number of bytes returned by getdirentries() or getdents(). And a value of zero is returned when the end of the directory has been reached — that's the "we're done here" signal 👑.

If the basep pointer value is non-NULL, the getdirentries() system call writes the position of the block read into the location pointed to by basep. Alternatively, the current position pointer may be set and retrieved by lseek(2). And like, the current position pointer should only be set to one of these values:

• a value returned by lseek(2)
• a value returned in the location pointed to by basep (getdirentries() only)
• a value returned in the d_off field, if it is non-zero
• or zero

⭐ That last bit is a vibe check, not a suggestion. Set your position pointer to anything else and you're on your own, bestie. 😭

---

🧚 IMPLEMENTATION NOTES 🧚

The d_off field is currently set to 0 by the NFS client, because the directory offset cookies returned by an NFS server cannot be used by lseek(2) at this time. So like… it's giving nothing. Zero. Empty. On purpose. 💀

---

🔥 RETURN VALUES 🔥

If successful, the number of bytes actually transferred is returned — slay 💖. Otherwise, -1 is returned and the global variable errno is set to indicate the error. 🙈

---

🌈 ERRORS 🌈

The getdirentries() system call will fail if:

• [EBADF] — The fd argument is not a valid file descriptor open for reading. Not her reading era, apparently.
• [EFAULT] — Either buf or non-NULL basep point outside the allocated address space. Rude.
• [EINVAL] — The value of nbytes is too small for returning a directory entry or block of entries, or the current position pointer is invalid.
• [EIO] — An I/O error occurred while reading from or writing to the file system. 😭
• [EINTEGRITY] — Corrupted data was detected while reading from the file system. Crunchy. Not in a good way.
• [ENOENT] — Directory unlinked but still open. She's ghosting but also still here. 🫶
• [ENOTDIR] — The file referenced by fd is not a directory. Wrong main character, wrong movie. 💀

---

🦋 SEE ALSO 🦋

lseek(2), open(2), directory(3), dir(5) — go read these next, iykyk 💅

---

⭐ HISTORY ⭐

The getdirentries() system call first appeared in 4.4BSD. The getdents() system call first appeared in FreeBSD 3.0. Vintage girlies, both of them ✨

---

and that's the whole page, bestie!! this one was from the Debian fam, dated July 8, 2025 — mwah, go read some directories 💖🎀🦋