HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |NOTES |SEE ALSO |COLOPHON | |
openat2(2) System Calls Manualopenat2(2)openat2 - open and possibly create a file (extended)
Standard C library (libc,-lc)
#include <fcntl.h>/* Definition ofO_*andS_*constants */#include <linux/openat2.h>/* Definition ofRESOLVE_*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(SYS_openat2, intdirfd, const char *path,struct open_how *how, size_tsize);Note: glibc provides no wrapper foropenat2(), necessitating the use ofsyscall(2).
Theopenat2() system call is an extension ofopenat(2) and provides a superset of its functionality. Theopenat2() system call opens the file specified bypath. If the specified file does not exist, it may optionally (ifO_CREAT is specified inhow.flags) be created. As withopenat(2), ifpath is relative, then it is interpreted relative to the directory referred to by the file descriptordirfd (or the current working directory of the calling process, ifdirfd is the special valueAT_FDCWD). Ifpath is absolute, thendirfd is ignored (unlesshow.resolve containsRESOLVE_IN_ROOT, in which casepath is resolved relative todirfd). Rather than taking a singleflags argument, an extensible structure (how) is passed to allow for future extensions. Thesize argument must be specified assizeof(struct open_how).The open_how structure Thehow argument specifies howpath should be opened, and acts as a superset of theflags andmode arguments toopenat(2). This argument is a pointer to anopen_how structure, described inopen_how(2type). Any future extensions toopenat2() will be implemented as new fields appended to theopen_how structure, with a zero value in a new field resulting in the kernel behaving as though that extension field was not present. Therefore, the callermust zero- fill this structure on initialization. (See the "Extensibility" section of theNOTESfor more detail on why this is necessary.) The fields of theopen_how structure are as follows:flags This field specifies the file creation and file status flags to use when opening the file. All of theO_*flags defined foropenat(2) are validopenat2() flag values. Whereasopenat(2) ignores unknown bits in itsflags argument,openat2() returns an error if unknown or conflicting flags are specified inhow.flags.mode This field specifies the mode for the new file, with identical semantics to themode argument ofopenat(2). Whereasopenat(2) ignores bits other than those in the range07777 in itsmode argument,openat2() returns an error ifhow.mode contains bits other than07777. Similarly, an error is returned ifopenat2() is called with a nonzerohow.mode andhow.flags does not containO_CREAT orO_TMPFILE.resolve This is a bit-mask of flags that modify the way in whichallcomponents ofpath will be resolved. (Seepath_resolution(7) for background information.) The primary use case for these flags is to allow trusted programs to restrict how untrusted paths (or paths inside untrusted directories) are resolved. The full list ofresolve flags is as follows:RESOLVE_BENEATH Do not permit the path resolution to succeed if any component of the resolution is not a descendant of the directory indicated bydirfd. This causes absolute symbolic links (and absolute values ofpath) 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 specifyRESOLVE_NO_MAGICLINKS.RESOLVE_IN_ROOT Treat the directory referred to bydirfd as the root directory while resolvingpath. Absolute symbolic links are interpreted relative todirfd. If a prefix component ofpath equates todirfd, then an immediately following.. component likewise equates todirfd (just as/.. is traditionally equivalent to/). Ifpath is absolute, it is also interpreted relative todirfd. The effect of this flag is as though the calling process had usedchroot(2) to (temporarily) modify its root directory (to the directory referred to bydirfd). However, unlikechroot(2) (which changes the filesystem root permanently for a process),RESOLVE_IN_ROOTallows a program to efficiently restrict path resolution on a per-open basis. 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 specifyRESOLVE_NO_MAGICLINKS.RESOLVE_NO_MAGICLINKS Disallow all magic-link resolution during path resolution. Magic links are symbolic link-like objects that are most notably found inproc(5); examples include/proc/pid/exe and/proc/pid/fd/*. (Seesymlink(7) for more details.) Unknowingly opening magic links can be risky for some applications. Examples of such risks include the following: • If the process opening a pathname is a controlling process that currently has no controlling terminal (seecredentials(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 theRESOLVE_NO_MAGICLINKSflag. If the trailing component (i.e., basename) ofpath is a magic link,how.resolve containsRESOLVE_NO_MAGICLINKS, andhow.flags contains bothO_PATHandO_NOFOLLOW, then anO_PATHfile descriptor referencing the magic link will be returned.RESOLVE_NO_SYMLINKS Disallow resolution of symbolic links during path resolution. This option impliesRESOLVE_NO_MAGICLINKS. If the trailing component (i.e., basename) ofpath is a symbolic link,how.resolve containsRESOLVE_NO_SYMLINKS, andhow.flags contains bothO_PATHandO_NOFOLLOW, then anO_PATHfile descriptor referencing the symbolic link will be returned. Note that the effect of theRESOLVE_NO_SYMLINKS flag, which affects the treatment of symbolic links in all of the components ofpath, differs from the effect of theO_NOFOLLOWfile creation flag (inhow.flags), which affects the handling of symbolic links only in the final component ofpath. Applications that employ theRESOLVE_NO_SYMLINKS flag are encouraged to make its use configurable (unless it is used for a specific security purpose), as 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 ofopenat2() 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.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 bydirfd, or on the same mount as the current working directory ifdirfd is specified asAT_FDCWD. Applications that employ theRESOLVE_NO_XDEVflag are encouraged to make its use configurable (unless it is 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 ofopenat2() 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 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 errorEAGAIN. 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. If any bits other than those listed above are set inhow.resolve, an error is returned.
On success, a new file descriptor is returned. On error, -1 is returned, anderrno is set to indicate the error.
The set of errors returned byopenat2() includes all of the errors returned byopenat(2), as well as the following additional errors:E2BIGAn extension that this kernel does not support was specified inhow. (See the "Extensibility" section ofNOTESfor more detail on how extensions are handled.)EAGAINhow.resolve contains eitherRESOLVE_IN_ROOTorRESOLVE_BENEATH, and the kernel could not ensure that a ".." component didn't escape (due to a race condition or potential attack). The caller may choose to retry theopenat2() call.EAGAIN RESOLVE_CACHEDwas set, and the open operation cannot be performed using only cached information. The caller should retry withoutRESOLVE_CACHEDset inhow.resolve.EINVALAn unknown flag or invalid value was specified inhow.EINVALmode is nonzero, buthow.flags does not containO_CREATorO_TMPFILE.EINVALsize was smaller than any known version ofstruct open_how.ELOOPhow.resolve containsRESOLVE_NO_SYMLINKS, and one of the path components was a symbolic link (or magic link).ELOOPhow.resolve containsRESOLVE_NO_MAGICLINKS, and one of the path components was a magic link.EXDEVhow.resolve contains eitherRESOLVE_IN_ROOTorRESOLVE_BENEATH, and an escape from the root during path resolution was detected.EXDEVhow.resolve containsRESOLVE_NO_XDEV, and a path component crosses a mount point.
Linux.
Linux 5.6. The semantics ofRESOLVE_BENEATHwere modeled after FreeBSD'sO_BENEATH.
Extensibility In order to allow for future extensibility,openat2() requires the user-space application to specify the size of theopen_how structure that it is passing. By providing this information, it is possible foropenat2() to provide both forwards- and backwards- compatibility, withsize acting as an implicit version number. (Because new extension fields will always be appended, the structure size will always increase.) This extensibility design is very similar to other system calls such assched_setattr(2),perf_event_open(2), andclone3(2). If we letusize be the size of the structure as specified by the user-space application, andksize be the size of the structure which the kernel supports, then there are three cases to consider: • Ifksize equalsusize, then there is no version mismatch andhow can be used verbatim. • Ifksize is larger thanusize, then there are some extension fields that the kernel supports which the user-space application is unaware of. Because a zero value in any added extension field signifies a no-op, the kernel treats all of the extension fields not provided by the user-space application as having zero values. This provides backwards-compatibility. • Ifksize is smaller thanusize, then there are some extension fields which the user-space application is aware of but which the kernel does not support. Because any extension field must have its zero values signify a no-op, the kernel can safely ignore the unsupported extension fields if they are all-zero. If any unsupported extension fields are nonzero, then -1 is returned anderrno is set toE2BIG. This provides forwards- compatibility. Because the definition ofstruct open_how may change in the future (with new fields being added when system headers are updated), user-space applications should zero-fillstruct open_how to ensure that recompiling the program with new headers will not result in spurious errors at run time. The simplest way is to use a designated initializer: struct open_how how = { .flags = O_RDWR, .resolve = RESOLVE_IN_ROOT }; or explicitly usingmemset(3) or similar: struct open_how how; memset(&how, 0, sizeof(how)); how.flags = O_RDWR; how.resolve = RESOLVE_IN_ROOT; A user-space application that wishes to determine which extensions the running kernel supports can do so by conducting a binary search onsize with a structure which has every byte nonzero (to find the largest value which doesn't produce an error ofE2BIG).openat(2),open_how(2type),path_resolution(7),symlink(7)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17openat2(2)Pages that refer to this page:io_uring_enter2(2), io_uring_enter(2), mount_setattr(2), open(2), open_how(2type), syscalls(2), io_uring_prep_openat2(3), io_uring_prep_openat2_direct(3), path_resolution(7), symlink(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |