openat2(2)

💅 openat2(2) — System Calls Manual 💅

okay bestie, welcome to openat2, the extended little sibling of openat(2) that said "let me be ✨extra✨". this is the openat2(2) manual page and it's long so buckle up 🎀

---

✨ NAME ✨

openat2 — open and possibly create a file (extended) 💖

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#include <fcntl.h>          /* Definition of O_* and S_* constants */
#include <linux/openat2.h>  /* Definition of RESOLVE_* constants */
#include <sys/syscall.h>    /* Definition of SYS_* constants */
#include <unistd.h>

long syscall(SYS_openat2, int dirfd, const char *path,
             struct open_how *how, size_t size);

heads up, bestie: glibc provides no wrapper for openat2(), so you literally have to go through syscall(2). no cap. 🫶

---

💖 DESCRIPTION 💖

so openat2() is the glow-up of openat(2) — it's an extension of it and gives you a superset of its functionality. it's giving main character energy fr fr.

openat2() opens the file specified by path. and if that file doesn't exist? it may optionally be created — but only if O_CREAT is specified in how.flags. (:sparkles:)

just like with openat(2): if path is relative, it gets interpreted relative to the directory that the file descriptor dirfd refers to — or, if dirfd is the special value AT_FDCWD, relative to the calling process's current working directory. and if path is absolute, then dirfd is ignored… unless how.resolve contains RESOLVE_IN_ROOT, in which case path gets resolved relative to dirfd instead. iykyk 😌

and here's the slay part: instead of taking a single flags argument, it takes an extensible structure (how) so it can grow new features later. the size argument must be specified as sizeof(struct open_how). no substitutions, bestie.

---

🌸 The open_how structure 🌸

the how argument is the moment. it specifies how path should be opened, and it acts as a superset of the flags and mode arguments to openat(2). it's a pointer to an open_how structure, which is described over in open_how(2type). 👑

any future extensions to openat2() will show up as new fields appended to the open_how structure, and a zero value in a new field means the kernel behaves as though that extension field wasn't even there. so therefore — and this is important, girlies — the caller MUST zero-fill this structure on initialization. (there's more about why this is necessary in the "Extensibility" section of the NOTES. check it later!)

the fields of the open_how structure are, in order:

🦋 flags

this field specifies the file creation and file status flags to use when opening the file. all of the O_* flags defined for openat(2) are valid openat2() flag values. ✅

now here's where it gets spicy 🌶️ — whereas openat(2) ignores unknown bits in its flags argument, openat2() returns an error if unknown or conflicting flags are specified in how.flags. it does not let things slide.

openat2() also supports this additional flag:

• OPENAT2_REGULAR (since Linux 7.2) — open the file specified by path only if it is a regular file. 💅

🍓 mode

this field specifies the mode for the new file, with identical semantics to the mode argument of openat(2).

but again, the glow-up: whereas openat(2) ignores bits other than those in the range 07777 in its mode argument, openat2() returns an error if how.mode contains bits other than 07777. and similarly, an error is returned if openat2() is called with a nonzero how.mode and how.flags does not contain O_CREAT or O_TMPFILE. so don't be messy with your bits. 🙈

💜 resolve

this one is the moment. it's a bit-mask of flags that modify the way all components of path will be resolved. (for background, go peek at path_resolution(7).)

the primary use case for these flags is letting trusted programs restrict how untrusted paths (or paths inside untrusted directories) are resolved. 🔐 the full list of resolve flags is:

• RESOLVE_BENEATH — do not permit the path resolution to succeed if any component of the resolution is not a descendant of the directory indicated by dirfd. this causes absolute symbolic links (and absolute values of path) to be rejected. 🚫

currently, this flag also disables magic-link resolution (see below). however, this may change in the future. therefore, to ensure that magic links are not resolved, the caller should explicitly specify RESOLVE_NO_MAGICLINKS. (future-proofing, bestie, it's a vibe 💅)

• RESOLVE_IN_ROOT — treat the directory referred to by dirfd as the root directory while resolving path. absolute symbolic links get interpreted relative to dirfd. if a prefix component of path equates to dirfd, then an immediately following .. component likewise equates to dirfd (just as /.. is traditionally equivalent to /). and if path is absolute, it is also interpreted relative to dirfd.

the effect of this flag is as though the calling process had used chroot(2) to (temporarily) modify its root directory — specifically to the directory referred to by dirfd. but — and this is the key difference — unlike chroot(2) (which changes the filesystem root permanently for a process), RESOLVE_IN_ROOT lets a program efficiently restrict path resolution on a per-open basis. iconic behavior honestly 👑

currently, this flag also disables magic-link resolution. however, this may change in the future. therefore, to ensure that magic links are not resolved, the caller should explicitly specify RESOLVE_NO_MAGICLINKS. (yes this is the same warning as above, it's important, don't skip it 🌸)

• RESOLVE_NO_MAGICLINKS — disallow all magic-link resolution during path resolution.

magic links are symbolic-link-like objects most notably found in proc(5); examples include /proc/pid/exe and /proc/pid/fd/*. (see symlink(7) for more deets.)

unknowingly opening magic links can be risky for some applications. examples of such risks include:

• if the process opening a pathname is a controlling process that currently has no controlling terminal (see credentials(7)), then opening a magic link inside /proc/pid/fd that happens to refer to a terminal would cause the process to acquire a controlling terminal. 😳
• in a containerized environment, a magic link inside /proc may refer to an object outside the container, and thus may provide a means to escape from the container. 💀

because of such risks, an application may prefer to disable magic link resolution using the RESOLVE_NO_MAGICLINKS flag. smart girl behavior.

and one more thing: if the trailing component (i.e., basename) of path is a magic link, how.resolve contains RESOLVE_NO_MAGICLINKS, and how.flags contains both O_PATH and O_NOFOLLOW, then an O_PATH file descriptor referencing the magic link will be returned. ✨

• RESOLVE_NO_SYMLINKS — disallow resolution of symbolic links during path resolution. this option implies RESOLVE_NO_MAGICLINKS. two birds, one flag 🦋

if the trailing component (i.e., basename) of path is a symbolic link, how.resolve contains RESOLVE_NO_SYMLINKS, and how.flags contains both O_PATH and O_NOFOLLOW, then an O_PATH file descriptor referencing the symbolic link will be returned.

note that the effect of the RESOLVE_NO_SYMLINKS flag — which affects the treatment of symbolic links in all of the components of path — differs from the effect of the O_NOFOLLOW file creation flag (in how.flags), which affects the handling of symbolic links only in the final component of path. yes, they are different, do not confuse them, bestie. 🙈

applications that employ the RESOLVE_NO_SYMLINKS flag are encouraged to make its use configurable (unless it's used for a specific security purpose), because symbolic links are very widely used by end-users. setting this flag indiscriminately — i.e., for purposes not specifically related to security — for all uses of openat2() may result in spurious errors on previously functional systems. 😭 this may occur if, for example, a system pathname that is used by an application is modified (e.g., in a new distribution release) so that a pathname component (now) contains a symbolic link. so like… don't just slap it everywhere, okay?

• RESOLVE_NO_XDEV — disallow traversal of mount points during path resolution (including all bind mounts). consequently, path must either be on the same mount as the directory referred to by dirfd, or on the same mount as the current working directory if dirfd is specified as AT_FDCWD.

applications that employ the RESOLVE_NO_XDEV flag are encouraged to make its use configurable (unless it's used for a specific security purpose), as bind mounts are widely used by end-users. setting this flag indiscriminately — i.e., for purposes not specifically related to security — for all uses of openat2() may result in spurious errors on previously functional systems. 😭 this may occur if, for example, a system pathname that is used by an application is modified (e.g., in a new distribution release) so that a pathname component (now) contains a bind mount.

• RESOLVE_CACHED (since Linux 5.12) — make the open operation fail unless all path components are already present in the kernel's lookup cache. if any kind of revalidation or I/O is needed to satisfy the lookup, openat2() fails with the error EAGAIN. 🔥 this is useful in providing a fast-path open that can be performed without resorting to thread offload, or other mechanisms that an application might use to offload slower operations. speed, bestie 💨

and finally, the plot twist: if any bits other than those listed above are set in how.resolve, an error is returned. 🚨

---

🔥 RETURN VALUE 🔥

on success, a new file descriptor is returned. 🎉

on error, -1 is returned, and errno is set to indicate the error. 😭

---

…and that's just part 1, bestie, there's more coming 🌈

💥 ERRORS 💥

okay bestie, so openat2() throws everything that its little sibling openat(2) throws — no cap — plus these extra ones below. take notes, this is the good part 📝✨

• E2BIG — someone passed an extension in how that this kernel straight up does not support. (peep the Extensibility section down in NOTES for the whole saga of how extensions get handled 👀)
• EAGAIN — how.resolve has either RESOLVE_IN_ROOT or RESOLVE_BENEATH set, and the kernel could not guarantee that a ".." component didn't just escape (either a race condition happened or somebody's being shady, lowkey an attack). the caller gets to pick: retry the openat2() call, it's giving second-chance energy 💅
• EAGAIN — RESOLVE_CACHED was set, but nope, this open operation cannot be done using only cached info. caller should retry with RESOLVE_CACHED not set in how.resolve. rip 🙈
• EINVAL — an unknown flag or an invalid value got dropped into how.
• EINVAL — mode is nonzero, but how.flags doesn't contain O_CREAT or O_TMPFILE. the audacity 💀
• EINVAL — size was smaller than any known version of struct open_how.
• ELOOP — how.resolve contains RESOLVE_NO_SYMLINKS, and one of the path components was a symbolic link (or a magic link). scandalous ✨
• ELOOP — how.resolve contains RESOLVE_NO_MAGICLINKS, and one of the path components was a magic link. double scandal 🦋
• EXDEV — how.resolve contains either RESOLVE_IN_ROOT or RESOLVE_BENEATH, and an escape from the root during path resolution was detected. caught in 4k 📸
• EXDEV — how.resolve contains RESOLVE_NO_XDEV, and a path component crosses a mount point.
• EFTYPE — how.flags contains the OPENAT2_REGULAR flag and the path is not a regular file. bestie it's simply not that girl 🎀

---

📜 STANDARDS 📜

Linux. that's it. that's the standard. periodt 👑

---

🕰️ HISTORY 🕰️

dropped in Linux 5.6 — vintage, iconic, we love her 💖

the semantics of RESOLVE_BENEATH were modeled after FreeBSD's O_BENEATH, but — and this is the tea ☕ — Linux avoided a well-known correctness bug in FreeBSD's implementation that made it effectively insecure. later, FreeBSD 13 introduced O_RESOLVE_BENEATH to replace the insecure O_BENEATH. FreeBSD's O_RESOLVE_BENEATH semantics are based on Linux's RESOLVE_BENEATH and the two are now functionally equivalent. the glow-up is real 🦋✨

---

📝 NOTES 📝

🧩 Extensibility 🧩

so, to allow for future extensibility and keep things cute, openat2() makes the user-space application specify the size of the open_how structure it's passing in. by handing over that info, openat2() gets both forwards- and backwards-compatibility, with size acting like an implicit version number. (because new extension fields always get appended, the structure size will always increase — it only goes up, it's giving growth mindset 🪴). this extensibility design is very similar to other system calls like sched_setattr(2), perf_event_open(2), and clone3(2).

okay so if we let usize be the size of the structure as specified by the user-space application, and ksize be the size of the structure that the kernel supports, there are like three cases to think about:

• if ksize equals usize, then there's no version mismatch and how can be used verbatim. slay 💅
• if ksize is larger than usize, then there are some extension fields the kernel supports that the user-space application doesn't even know about. because a zero value in any added extension field means no-op, the kernel treats every extension field the user-space app didn't provide as having zero values. this provides backwards-compatibility.
• if ksize is smaller than usize, then there are some extension fields the user-space application is aware of but the kernel does not support. because any extension field must have its zero values mean no-op, the kernel can safely ignore the unsupported extension fields if they're all-zero. but if any unsupported extension field is nonzero — boom 💥 — -1 is returned and errno is set to E2BIG. this provides forwards-compatibility.

because the definition of struct open_how may change in the future (new fields getting added whenever system headers are updated), user-space applications should zero-fill struct open_how to make sure that recompiling the program with new headers won't result in spurious errors at run time. 😭 the simplest way is a designated initializer:

struct open_how how = { .flags = O_RDWR,
                        .resolve = RESOLVE_IN_ROOT };

or you can do it explicitly with memset(3) or similar:

struct open_how how;
memset(&how, 0, sizeof(how));
how.flags = O_RDWR;
how.resolve = RESOLVE_IN_ROOT;

and if a user-space application wants to find out which extensions the running kernel supports? so easy bestie — do a binary search on size with a structure that has every byte nonzero (the goal is finding the largest value that doesn't produce an error of E2BIG). detective work, but make it ✨algorithmic✨ 🔍

---

👀 SEE ALSO 👀

openat(2), open_how(2type), path_resolution(7), symlink(7)

go read those, they're all bangers, iykyk 🫶

---

and that's a wrap on openat2(2) bestie!! this page came to you from Linux man-pages 6.20, dated 2026-07-02 — go forth and resolve some paths safely, you absolute main character 👑🌈💜