GETDIRENTRIES(2)

💖 GETDIRENTRIES — the getdirentries(2) glow-up 💖

okay bestie, pull up a chair, we're reading a section 2 system call page together and honestly? it's giving directory archaeology. this is from the System Calls Manual, and it covers two lil syscalls that are basically the same energy: getdirentries and getdents. 🎀

---

✨ NAME ✨

getdirentries, getdents — grab directory entries, but make it file-system-independent. no cap. 🦋

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). she lives in the C library, as she should. 💅

---

🌸 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);

two icons, two signatures, one purpose. 🫶

---

💫 DESCRIPTION 💫

so like. getdirentries() and getdents() read directory entries out of the directory that the file descriptor fd is pointing at, and they dump them into the buffer that buf points to — in a format that doesn't care which file system you're on. file system independent, periodt. 🌈

up to nbytes of data gets transferred. but here's the thing, and listen closely: the nbytes argument must be greater than or equal to the block size associated with the file — go check stat(2) for that. and ngl, some file systems might straight up not support these system calls with buffers smaller than that size. so don't be cute with your buffer sizing. 💀

the data chilling in that buffer is a whole series of dirent structures, and each one is carrying:

      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 squad one by one, because every single field matters and we are NOT skipping any:

• d_fileno — a number that's unique for each distinct file in the file system. files that are linked by hard links (peep link(2)) share the same d_fileno. matching numbers = same file, that's the vibe check. 🔥
• d_off — returns a cookie 🍪 that you can hand to lseek(2) to position the directory descriptor onto the next entry. yes, they really call it a cookie, and yes, it's iconic.
• d_reclen — the length, in bytes, of the directory record. that's it, that's the field. 📏
• d_type — the type of the file that the directory record is pointing at. the file type values are defined in <sys/dirent.h>. go look, iykyk.
• d_name — a null terminated file name. cute, simple, terminates.
• d_namlen — the length of the file name excluding the null byte. so the actual size of d_name can vary anywhere from 1 to MAXNAMLEN + 1. she contains multitudes. 🦋

entries may be separated by extra space, bestie — they're not always packed tight. that's why the d_reclen entry can be used as an offset from the start of a dirent structure to the next structure, if there even is one.

the actual number of bytes transferred gets returned. the current position pointer associated with fd gets set to point at the next block of entries. but — and this is the sneaky part — the pointer may not advance by the number of bytes returned by getdirentries() or getdents(). 😭 do not assume the math works out like that, because it doesn't. a value of zero comes back when you've hit the end of the directory, i.e. you're done, go home. 🏁

now, if the basep pointer value is non-NULL, the getdirentries() system call writes the position of the block it read into the location that basep points to. alternatively, the current position pointer can be set and retrieved with lseek(2). and here's the rule for that pointer, bestie, no exceptions:

the current position pointer should only be set to 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, or zero. that's the list. that's the whole list. 🙈

---

🧚 IMPLEMENTATION NOTES 🧚

the d_off field is being used as a cookie for readdir for nfs servers. these cookies can be cached, and they let you read directory entries at a specific offset on demand. like, on demand. obsessed. 💜

---

⭐ RETURN VALUES ⭐

if it works: the number of bytes actually transferred gets returned. slay. ✨

otherwise: -1 comes back and the global variable errno gets 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. bestie, it's not even a door.
• [EFAULT] — either buf or a non-NULL basep point outside the allocated address space. they're pointing into the void 💀
• [EINVAL] — the file referenced by fd is not a directory, or nbytes is too small for returning a directory entry or block of entries, or the current position pointer is invalid. three whole ways to be wrong.
• [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. the data came back cursed. 🫠

---

👀 SEE ALSO 👀

• lseek(2)
• open(2)

---

📜 HISTORY 📜

the getdirentries() system call first appeared in 4.4BSD. the getdents() system call first appeared in FreeBSD 3.0. they've been doing this since before most of us could walk. respect the elders. 👑

---

and that's the whole page, bestie!! 🎀 this one came to you courtesy of Debian, dated March 30, 2020, under the GETDIRENTRIES(2) banner. go forth and read some directory entries responsibly 💅✨