telldir(3)

💖 telldir(3) — the bestie who tells you exactly where you're at 💖

okay so this one lives in the Library Functions Manual and it's genuinely such a little icon. it's giving "where am I in this directory stream bestie" and honestly? we love that for us. 🫶

---

✨ NAME ✨

telldir — return current location in directory stream 📍

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🌸 SYNOPSIS 🌸

#include <dirent.h>

long telldir(DIR *dirp);

🧚 Feature Test Macro Requirements for glibc (peep feature_test_macros(7))

telldir():

_XOPEN_SOURCE
   || /* glibc >= 2.19: */ _DEFAULT_SOURCE
   || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

---

💅 DESCRIPTION 💅

So telldir() hands you back the current location that's associated with the directory stream dirp. That's it. That's the whole vibe. A little receipt for where you are. 🧾✨

---

🌈 RETURN VALUE 🌈

When it's slaying (success), telldir() returns the current location inside the directory stream. 💖

When it's not (error), you get -1 back, and errno gets set to tell you what went wrong. 😭

---

💀 ERRORS 💀

• EBADF — the directory stream descriptor dirp is invalid. not a valid stream bestie, that's a no from me 🙈

---

👑 ATTRIBUTES 👑

for the whole explanation of what these terms even mean, go see attributes(7) — iykyk.

• Interface: telldir()
• Attribute: Thread safety
• Value: MT-Safe 🔥

---

⭐ STANDARDS ⭐

POSIX.1-2008. periodt. 💅

---

🦋 HISTORY 🦋

POSIX.1-2001, 4.3BSD. it's been around, it's got lore. 📜

Up to glibc 2.1.1, the return type of telldir() was off_t. then POSIX.1-2001 came through and specified long, and that's the type that's been used since glibc 2.1.2. glow-up fr fr ✨

okay now the important part, listen up: in early filesystems, the value returned by telldir() was just a simple file offset within a directory. cute, simple, flat. BUT modern filesystems use tree or hash structures instead of flat tables to represent directories, and on those filesystems the value returned by telldir() (which also gets used internally by readdir(3)) is a "cookie" 🍪 that the implementation uses to derive a position within the directory.

🚨 MAJOR WARNING 🚨 Application programs should treat this strictly as an opaque value, making no assumptions about its contents. do not peek inside the cookie. do not decode the cookie. do not build your whole personality on guessing what the cookie means. just hold it and hand it back. 🔒

---

🎀 SEE ALSO 🎀

closedir(3), opendir(3), readdir(3), rewinddir(3), scandir(3), seekdir(3)

---

and that's the whole page babes 💖 this one came straight out of Linux man-pages 6.20, dated 2026-02-08 — go off, telldir(3), you opaque little cookie queen 🍪👑🫶