1 .\" Copyright (C) 2019 Aleksa Sarai <cyphar@cyphar.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .TH OPENAT2 2 2021-03-22 "Linux" "Linux Programmer's Manual"
26 openat2 \- open and possibly create a file (extended)
29 .BR "#include <fcntl.h>" \
30 " /* Definition of " O_* " and " S_* " constants */"
31 .BR "#include <linux/openat2.h>" " /* Definition of " RESOLVE_* " constants */"
32 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
33 .B #include <unistd.h>
35 .BI "long syscall(SYS_openat2, int " dirfd ", const char *" pathname ,
36 .BI " struct open_how *" how ", size_t " size );
40 glibc provides no wrapper for
42 necessitating the use of
47 system call is an extension of
49 and provides a superset of its functionality.
53 system call opens the file specified by
55 If the specified file does not exist, it may optionally (if
65 is a relative pathname, then it is interpreted relative to the
66 directory referred to by the file descriptor
68 (or the current working directory of the calling process, if
74 is an absolute pathname, then
82 is resolved relative to
85 Rather than taking a single
87 argument, an extensible structure (\fIhow\fP) is passed to allow for
91 argument must be specified as
92 .IR "sizeof(struct open_how)" .
94 .SS The open_how structure
97 argument specifies how
99 should be opened, and acts as a superset of the
105 This argument is a pointer to a structure of the following form:
110 u64 flags; /* O_* flags */
111 u64 mode; /* Mode for O_{CREAT,TMPFILE} */
112 u64 resolve; /* RESOLVE_* flags */
118 Any future extensions to
120 will be implemented as new fields appended to the above structure,
121 with a zero value in a new field resulting in the kernel behaving
122 as though that extension field was not present.
123 Therefore, the caller
125 zero-fill this structure on
127 (See the "Extensibility" section of the
129 for more detail on why this is necessary.)
133 structure are as follows:
137 the file creation and file status flags to use when opening the file.
148 ignores unknown bits in its
152 returns an error if unknown or conflicting flags are specified in
156 This field specifies the
157 mode for the new file, with identical semantics to the
164 ignores bits other than those in the range
172 contains bits other than
174 Similarly, an error is returned if
176 is called with a nonzero
186 This is a bit-mask of flags that modify the way in which
192 .BR path_resolution (7)
193 for background information.)
195 The primary use case for these flags is to allow trusted programs to restrict
196 how untrusted paths (or paths inside untrusted directories) are resolved.
203 .\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0
204 Do not permit the path resolution to succeed if any component of the resolution
205 is not a descendant of the directory indicated by
207 This causes absolute symbolic links (and absolute values of
211 Currently, this flag also disables magic-link resolution (see below).
212 However, this may change in the future.
213 Therefore, to ensure that magic links are not resolved,
214 the caller should explicitly specify
215 .BR RESOLVE_NO_MAGICLINKS .
218 .\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994
219 Treat the directory referred to by
221 as the root directory while resolving
223 Absolute symbolic links are interpreted relative to
225 If a prefix component of
229 then an immediately following
231 component likewise equates to
235 is traditionally equivalent to
239 is an absolute path, it is also interpreted relative to
242 The effect of this flag is as though the calling process had used
244 to (temporarily) modify its root directory (to the directory
249 (which changes the filesystem root permanently for a process),
251 allows a program to efficiently restrict path resolution on a per-open basis.
253 Currently, this flag also disables magic-link resolution.
254 However, this may change in the future.
255 Therefore, to ensure that magic links are not resolved,
256 the caller should explicitly specify
257 .BR RESOLVE_NO_MAGICLINKS .
259 .B RESOLVE_NO_MAGICLINKS
260 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
261 Disallow all magic-link resolution during path resolution.
263 Magic links are symbolic link-like objects that are most notably found in
268 .IR /proc/[pid]/fd/* .
273 Unknowingly opening magic links can be risky for some applications.
274 Examples of such risks include the following:
277 If the process opening a pathname is a controlling process that
278 currently has no controlling terminal (see
279 .BR credentials (7)),
280 then opening a magic link inside
282 that happens to refer to a terminal
283 would cause the process to acquire a controlling terminal.
285 .\" From https://lwn.net/Articles/796868/:
286 .\" The presence of this flag will prevent a path lookup operation
287 .\" from traversing through one of these magic links, thus blocking
288 .\" (for example) attempts to escape from a container via a /proc
289 .\" entry for an open file descriptor.
290 In a containerized environment,
293 may refer to an object outside the container,
294 and thus may provide a means to escape from the container.
297 Because of such risks,
298 an application may prefer to disable magic link resolution using the
299 .BR RESOLVE_NO_MAGICLINKS
302 If the trailing component (i.e., basename) of
307 .BR RESOLVE_NO_MAGICLINKS ,
316 file descriptor referencing the magic link will be returned.
318 .B RESOLVE_NO_SYMLINKS
319 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
320 Disallow resolution of symbolic links during path resolution.
322 .BR RESOLVE_NO_MAGICLINKS .
324 If the trailing component (i.e., basename) of
329 .BR RESOLVE_NO_SYMLINKS ,
338 file descriptor referencing the symbolic link will be returned.
340 Note that the effect of the
341 .BR RESOLVE_NO_SYMLINKS
343 which affects the treatment of symbolic links in all of the components of
345 differs from the effect of the
347 file creation flag (in
349 which affects the handling of symbolic links only in the final component of
352 Applications that employ the
353 .BR RESOLVE_NO_SYMLINKS
354 flag are encouraged to make its use configurable
355 (unless it is used for a specific security purpose),
356 as symbolic links are very widely used by end-users.
357 Setting this flag indiscriminately\(emi.e.,
358 for purposes not specifically related to security\(emfor all uses of
360 may result in spurious errors on previously functional systems.
361 This may occur if, for example,
362 a system pathname that is used by an application is modified
363 (e.g., in a new distribution release)
364 so that a pathname component (now) contains a symbolic link.
367 .\" commit 72ba29297e1439efaa54d9125b866ae9d15df339
368 Disallow traversal of mount points during path resolution (including all bind
372 must either be on the same mount as the directory referred to by
374 or on the same mount as the current working directory if
379 Applications that employ the
381 flag are encouraged to make its use configurable (unless it is
382 used for a specific security purpose),
383 as bind mounts are widely used by end-users.
384 Setting this flag indiscriminately\(emi.e.,
385 for purposes not specifically related to security\(emfor all uses of
387 may result in spurious errors on previously functional systems.
388 This may occur if, for example,
389 a system pathname that is used by an application is modified
390 (e.g., in a new distribution release)
391 so that a pathname component (now) contains a bind mount.
394 Make the open operation fail unless all path components are already present
395 in the kernel's lookup cache.
396 If any kind of revalidation or I/O is needed to satisfy the lookup,
400 This is useful in providing a fast-path open that can be performed without
401 resorting to thread offload, or other mechanisms that an application might
402 use to offload slower operations.
405 If any bits other than those listed above are set in
407 an error is returned.
409 On success, a new file descriptor is returned.
410 On error, \-1 is returned, and
412 is set to indicate the error.
414 The set of errors returned by
416 includes all of the errors returned by
418 as well as the following additional errors:
421 An extension that this kernel does not support was specified in
423 (See the "Extensibility" section of
425 for more detail on how extensions are handled.)
432 .BR RESOLVE_BENEATH ,
433 and the kernel could not ensure that a ".." component didn't escape (due to a
434 race condition or potential attack).
435 The caller may choose to retry the
441 was set, and the open operation cannot be performed using only cached
443 The caller should retry without
449 An unknown flag or invalid value was specified in
463 was smaller than any known version of
464 .IR "struct open_how" .
469 .BR RESOLVE_NO_SYMLINKS ,
470 and one of the path components was a symbolic link (or magic link).
475 .BR RESOLVE_NO_MAGICLINKS ,
476 and one of the path components was a magic link.
483 .BR RESOLVE_BENEATH ,
484 and an escape from the root during path resolution was detected.
489 .BR RESOLVE_NO_XDEV ,
490 and a path component crosses a mount point.
493 first appeared in Linux 5.6.
494 .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179
496 This system call is Linux-specific.
500 were modeled after FreeBSD's
504 In order to allow for future extensibility,
506 requires the user-space application to specify the size of the
508 structure that it is passing.
509 By providing this information, it is possible for
511 to provide both forwards- and backwards-compatibility, with
513 acting as an implicit version number.
514 (Because new extension fields will always
515 be appended, the structure size will always increase.)
516 This extensibility design is very similar to other system calls such as
517 .BR sched_setattr (2),
518 .BR perf_event_open (2),
524 be the size of the structure as specified by the user-space application, and
526 be the size of the structure which the kernel supports, then there are
527 three cases to consider:
533 then there is no version mismatch and
535 can be used verbatim.
541 then there are some extension fields that the kernel supports
542 which the user-space application
544 Because a zero value in any added extension field signifies a no-op,
546 treats all of the extension fields not provided by the user-space application
547 as having zero values.
548 This provides backwards-compatibility.
554 then there are some extension fields which the user-space application
555 is aware of but which the kernel does not support.
556 Because any extension field must have its zero values signify a no-op,
558 safely ignore the unsupported extension fields if they are all-zero.
559 If any unsupported extension fields are nonzero, then \-1 is returned and
563 This provides forwards-compatibility.
565 Because the definition of
567 may change in the future (with new fields being added when system headers are
568 updated), user-space applications should zero-fill
570 to ensure that recompiling the program with new headers will not result in
571 spurious errors at runtime.
572 The simplest way is to use a designated
577 struct open_how how = { .flags = O_RDWR,
578 .resolve = RESOLVE_IN_ROOT };
589 memset(&how, 0, sizeof(how));
591 how.resolve = RESOLVE_IN_ROOT;
595 A user-space application that wishes to determine which extensions
596 the running kernel supports can do so by conducting a binary search on
598 with a structure which has every byte nonzero (to find the largest value
599 which doesn't produce an error of
603 .BR path_resolution (7),