chroot(2)

✨ chroot(2) — change root directory ✨

okay bestie, welcome to the chroot(2) page in the System Calls Manual 💖 this one is tea, this one is drama, this one gets people in trouble, so let's get into it 🫶

---

🎀 NAME 🎀

chroot — change root directory. that's it, that's the whole name. short, iconic, dangerous, we love her ✨

---

📚 LIBRARY 📚

Standard C library, aka libc, aka link it with -lc 💅

---

🦋 SYNOPSIS 🦋

#include <unistd.h>

int chroot(const char *path);

✨ Feature Test Macro Requirements for glibc ✨

(peep feature_test_macros(7) for the whole lore, bestie)

chroot():
    Since glibc 2.2.2:
        _XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
            || /* Since glibc 2.20: */ _DEFAULT_SOURCE
            || /* glibc <= 2.19: */ _BSD_SOURCE
    Before glibc 2.2.2:
        none

like. the era of glibc you're living in literally changes your requirements. timeline queen behavior 😭

---

💖 DESCRIPTION 💖

so chroot() changes the root directory of the calling process to whatever you put in path. that directory becomes the one used for pathnames that start with /. and here's the thing — it's inherited by all the children of the calling process. the whole family gets the new root, no cap 👑

only a privileged process may call chroot(). on Linux that means a process with the CAP_SYS_CHROOT capability in its user namespace. everyone else? denied. sorry babes 💀

now here's the part that's giving reality check: this call changes one ingredient in the pathname resolution process and does nothing else. that's the entire plot. in particular, it is not intended to be used for any kind of security purpose — neither to fully sandbox a process nor to restrict filesystem system calls. periodt.

in the past, chroot() has been used by daemons to restrict themselves before passing paths supplied by untrusted users to system calls like open(2). but if a folder is moved out of the chroot directory, an attacker can exploit that to get out of the chroot directory as well. the easiest way to do that is to chdir(2) to the to-be-moved directory, wait for it to be moved out, then open a path like ../../../etc/passwd. like… that's it. that's the whole escape. so rude 😭

a slightly trickier variation also works under some circumstances if chdir(2) is not permitted. if a daemon allows a "chroot directory" to be specified, that usually means that if you want to prevent remote users from accessing files outside the chroot directory, you must ensure that folders are never moved out of it. that's the assignment, bestie 🎀

this call does not change the current working directory, so after the call '.' can be outside the tree rooted at '/'. in particular, the superuser can escape from a "chroot jail" by doing: c mkdir foo; chroot foo; cd ..; yeah. the root user just walked out. slay in the worst way 🙈

also — this call does not close open file descriptors, and such file descriptors may allow access to files outside the chroot tree. so if you left a door open before you locked up, the door stays open. highkey a plot hole 🔥

---

⭐ RETURN VALUE ⭐

• success — 0 is returned. it's giving we did it 🫶
• error — -1 is returned, and errno is set to indicate the error. it's giving not us 💀

---

🌸 ERRORS 🌸

depending on the filesystem, other errors can be returned. the more general errors are listed below, queen 🧚

• EACCES — search permission is denied on a component of the path prefix. (see also path_resolution(7).) so you're not allowed to peek in the corridor 👀
• EFAULT — path points outside your accessible address space. that memory is not yours, bestie, hands off 💅
• EIO — an I/O error occurred. the disk said no 😭
• ELOOP — too many symbolic links were encountered in resolving path. the symlinks are linking in circles, it's giving toxic situationship 🔄
• ENAMETOOLONG — path is too long. bestie that path is unwell 💀
• ENOENT — the file does not exist. she's not there, hun 😔
• ENOMEM — insufficient kernel memory was available. out of memory, out of vibes 😩
• ENOTDIR — a component of path is not a directory. you brought a file to a directory party 🎀
• EPERM — the caller has insufficient privilege. you tried and the kernel said who do you think you are ✋👑

---

👑 STANDARDS 👑

None. not standard. not standardized. free-spirited. no rules. a true main character 🌈

---

🕰️ HISTORY 🕰️

SVr4, 4.4BSD, SUSv1 (marked TO BE WITHDRAWN), SUSv2 (marked LEGACY). and heads up — this function is not part of POSIX.1-2001. she's an elder but she's not posix-certified, iykyk 💜

---

💅 NOTES 💅

• a child process created via fork(2) inherits its parent's root directory. family tree, literally 🌳
• the root directory is left unchanged by execve(2). new program, same root, she's consistent ✨
• the magic symbolic link, /proc/pid/root, can be used to discover a process's root directory. see proc(5) for details 🔍
• FreeBSD has a stronger jail() system call. good for them honestly 🏖️

---

🔥 SEE ALSO 🔥

• chroot(1)
• chdir(2)
• pivot_root(2)
• path_resolution(7)
• switch_root(8)

---

and that's a wrap babes 💖 this page was pulled from Linux man-pages 6.20, dated 2026-02-08 — go forth, root responsibly, and remember: chroot is not a security boundary no matter how many daemons pretend otherwise 🫶✨ stay safe, stay privileged, and don't cd .. on the way out 👑🎀