chdir(2)

💫 chdir, fchdir — changing where you live (your working directory, bestie)

okay so real talk: this is chdir(2), the system calls manual page, and it's genuinely one of the most useful lil pages in the whole book. If you've ever wanted your program to move to a different directory instead of just yapping about paths, this is the one. Let's get into it 💅

---

✨ LIBRARY ✨

Standard C library, aka libc, link it with -lc. The classics 🎀

---

🌸 SYNOPSIS 🌸

#include <unistd.h>

int chdir(const char *path);
int fchdir(int fd);

🦋 Feature Test Macro Requirements for glibc 🦋

(genuinely just go read feature_test_macros(7) if you wanna know the whole lore)

For fchdir():

_XOPEN_SOURCE >= 500
    || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
    || /* glibc up to and including 2.19: */ _BSD_SOURCE

yes bestie the comments are literally in the macro, that's not me being cute, that's just how it's written 😭

---

💖 DESCRIPTION 💖

chdir() changes the current working directory of the process that's calling it, and it sends it to whatever directory you named in <italic>path*. It's giving "we live here now." 🏡

fchdir() is literally identical to chdir(). The only difference — the one difference, no cap — is that instead of a path you hand it an open file descriptor. Same energy, different entrance 🚪

---

🔥 RETURN VALUE 🔥

• Slay (success): returns zero ✨
• Not slay (error): returns -1, and errno gets set to tell you exactly what went wrong 👑

---

💀 ERRORS 💀

Heads up: depending on what filesystem you're on, other errors can pop up too. But here are the more general ones for chdir():

• EACCES — search permission was denied for one of the components of <italic>path*. (go peek at path_resolution(7) for the full saga)
• EFAULT — <italic>path* is pointing somewhere outside your accessible address space. Rude.
• EIO — an I/O error happened, it's giving haunted hardware 🫠
• ELOOP — wayyy too many symbolic links got encountered while resolving <italic>path*.
• ENAMETOOLONG — <italic>path* is too long. bestie. it's too long.
• ENOENT — the directory you named in <italic>path* does not exist 😭
• ENOMEM — insufficient kernel memory was available.
• ENOTDIR — a component of <italic>path* is not a directory.

And now the general errors for fchdir():

• EACCES — search permission was denied on the directory that's open on fd.
• EBADF — fd is not a valid file descriptor 🙈
• ENOTDIR — fd does not refer to a directory.

---

👑 STANDARDS 👑

POSIX.1-2024. periodt.

---

🌈 HISTORY 🌈

• chdir() — SVr4, POSIX.1-1988, 4.4BSD.
• fchdir() — SVr4, 4.4BSD, SUSv1, POSIX.1-2001 XSI, POSIX.1-2008.

look at her, she's been iconic since the 80s 💜

---

🧚 NOTES 🧚

The current working directory is the starting point for interpreting relative pathnames — you know, the ones that don't start with '/'. So like, "../somedir" means "from wherever I am right now," which is exactly why this call matters so much 👀

A child process created via fork(2) inherits its parent's current working directory. But — and this is the part people forget — the current working directory is left unchanged by execve(2). So it survives the exec, no notes ✨

---

🫶 SEE ALSO 🫶

• chroot(2)
• getcwd(3)
• path_resolution(7)

---

and that's the whole page, bestie!! this one came from Linux man-pages 6.20, dated 2026-02-08, and it's the chdir(2) page 💖 go change some directories, you absolute icon 🦋✨