mkdir(2)

💖 mkdir(2) — the System Calls Manual's glow-up edition 💖

okay bestie, welcome to mkdir(2) from the System Calls Manual — which is lowkey the most iconic syscall for making a whole new folder out of thin air. new directory just dropped ✨

---

🌸 NAME 🌸

mkdir, mkdirat — create a directory 🎀

📚 LIBRARY 📚

Standard C library (libc, -lc) — she's standard, she's classic, she's in every libc 💅

✨ SYNOPSIS ✨

#include <sys/stat.h>

int mkdir(const char *path, mode_t mode);

#include <fcntl.h>           /* Definition of AT_* constants */
#include <sys/stat.h>

int mkdirat(int dirfd, const char *path, mode_t mode);

🧚 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):

mkdirat():

• Since glibc 2.10:
  • _POSIX_C_SOURCE >= 200809L
• Before glibc 2.10:
  • _ATFILE_SOURCE

---

🦋 DESCRIPTION 🦋

so mkdir() attempts to create a directory named path. attempts!! she's trying her best bestie 😭

The argument mode specifies the mode for the new directory (see inode(7)). It is modified by the process's umask in the usual way: in the absence of a default ACL, the mode of the created directory is (mode & ~umask & 0777). Whether other mode bits are honored for the created directory depends on the operating system. For Linux, see VERSIONS below. yes you literally have to scroll down, i don't make the rules 🙈

The newly created directory will be owned by the effective user ID of the process. and the group?? okay so if the directory containing the file has the set-group-ID bit set, or if the filesystem is mounted with BSD group semantics (mount -o bsdgroups or, synonymously mount -o grpid), then the new directory will inherit the group ownership from its parent; otherwise it will be owned by the effective group ID of the process. familial vibes fr fr 🫶

If the parent directory has the set-group-ID bit set, then so will the newly created directory. like mother like daughter, the bit gets passed down 👑

🌈 mkdirat() 🌈

mkdirat() operates in exactly the same way as mkdir(), except for the differences described here. she's her sister, not her clone 💜

If path is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd — rather than relative to the current working directory of the calling process, as is done by mkdir() for a relative pathname.

If path is relative and dirfd is the special value AT_FDCWD, then path is interpreted relative to the current working directory of the calling process (like mkdir()). classic behavior, we love a fallback 🎀

If path is absolute, then dirfd is ignored. sorry girl, you're not needed 💀

See openat(2) for an explanation of the need for mkdirat().

---

⭐ RETURN VALUE ⭐

mkdir() and mkdirat() return zero on success. On error, -1 is returned and errno is set to indicate the error. zero = slay, -1 = check errno, periodt 💅

---

🔥 ERRORS 🔥

get comfy, bestie, there's a whole list. every single one matters, no skipping 🙏

• EACCES — The parent directory does not allow write permission to the process, or one of the directories in path did not allow search permission. (See also path_resolution(7).)
• EBADF — (mkdirat()) path is relative but dirfd is neither AT_FDCWD nor a valid file descriptor. fake fd behavior, we don't know her 💀
• EDQUOT — The user's quota of disk blocks or inodes on the filesystem has been exhausted.
• EEXIST — path already exists (not necessarily as a directory). This includes the case where path is a symbolic link, dangling or not. she's already here, go home 🫠
• EFAULT — path points outside your accessible address space.
• EINVAL — The final component ("basename") of the new directory's path is invalid (e.g., it contains characters not permitted by the underlying filesystem). the name is giving illegal characters 😭
• ELOOP — Too many symbolic links were encountered in resolving path. link loop loop loop 🌀
• EMLINK — The number of links to the parent directory would exceed LINK_MAX.
• ENAMETOOLONG — path was too long. girl same
• ENOENT — A directory component in path does not exist or is a dangling symbolic link. she's not there and never was 🙈
• ENOMEM — Insufficient kernel memory was available.
• ENOSPC — The device containing path has no room for the new directory. the disk said "no room at the inn" 🍓
• ENOSPC — The new directory cannot be created because the user's disk quota is exhausted. same error, different reason, she's versatile like that 💅
• ENOTDIR — A component used as a directory in path is not, in fact, a directory. imposter syndrome but make it filesystem 👀
• ENOTDIR — (mkdirat()) path is relative and dirfd is a file descriptor referring to a file other than a directory.
• EPERM — The filesystem containing path does not support the creation of directories. this fs said absolutely not 🚫
• EROFS — path refers to a file on a read-only filesystem. ice cold, frozen, cannot write 🧊
• EOVERFLOW — UID or GID mappings (see user_namespaces(7)) have not been configured.

okay so like — heads up, ENOSPC and ENOTDIR each show up twice in this list on purpose. same error code, totally different cause. don't come for me, come for the kernel 🫶

---

🌸 VERSIONS 🌸

Under Linux, apart from the permission bits, the S_ISVTX mode bit is also honored. the sticky bit is that girl ✨

🎀 glibc notes 🎀

On older kernels where mkdirat() is unavailable, the glibc wrapper function falls back to the use of mkdir(). When path is relative, glibc constructs a pathname based on the symbolic link in /proc/self/fd that corresponds to the dirfd argument. improvising, adapting, overcoming 💖

---

👑 STANDARDS 👑

POSIX.1-2024.

---

🧚 HISTORY 🧚

• mkdir()
  • 4.2BSD, SVr4, POSIX.1-1988.
• mkdirat()
  • glibc 2.4, Linux 2.6.16, POSIX.1-2008.

look at these vintage queens, ancient lineage, still thriving 💜

---

🌈 NOTES 🌈

There are many infelicities in the protocol underlying NFS. Some of these affect mkdir(). nfs stays messy, i fear 😭

---

💫 SEE ALSO 💫

mkdir(1), chmod(2), chown(2), mknod(2), mount(2), rmdir(2), stat(2), umask(2), unlink(2), acl(5), path_resolution(7)

---

and that's the whole page bestie!! go forth and make directories responsibly 💖✨🎀🦋

this has been mkdir(2), brought to you by Linux man-pages 6.20, dated 2026-02-11 — mwah, ily, drink water 💅🌸