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 2020-11-01 "Linux" "Linux Programmer's Manual"
26 openat2 \- open and possibly create a file (extended)
29 .B #include <sys/stat.h>
31 .B #include <linux/openat2.h>
33 .BI "long openat2(int " dirfd ", const char *" pathname ,
34 .BI " struct open_how *" how ", size_t " size );
38 There is no glibc wrapper for this system call; see NOTES.
42 system call is an extension of
44 and provides a superset of its functionality.
48 system call opens the file specified by
50 If the specified file does not exist, it may optionally (if
60 is a relative pathname, then it is interpreted relative to the
61 directory referred to by the file descriptor
63 (or the current working directory of the calling process, if
69 is an absolute pathname, then
77 is resolved relative to
80 Rather than taking a single
82 argument, an extensible structure (\fIhow\fP) is passed to allow for
86 argument must be specified as
87 .IR "sizeof(struct open_how)" .
89 .SS The open_how structure
92 argument specifies how
94 should be opened, and acts as a superset of the
100 This argument is a pointer to a structure of the following form:
105 u64 flags; /* O_* flags */
106 u64 mode; /* Mode for O_{CREAT,TMPFILE} */
107 u64 resolve; /* RESOLVE_* flags */
113 Any future extensions to
115 will be implemented as new fields appended to the above structure,
116 with a zero value in a new field resulting in the kernel behaving
117 as though that extension field was not present.
118 Therefore, the caller
120 zero-fill this structure on
122 (See the "Extensibility" section of the
124 for more detail on why this is necessary.)
128 structure are as follows:
132 the file creation and file status flags to use when opening the file.
143 ignores unknown bits in its
147 returns an error if unknown or conflicting flags are specified in
151 This field specifies the
152 mode for the new file, with identical semantics to the
159 ignores bits other than those in the range
167 contains bits other than
169 Similarly, an error is returned if
171 is called with a nonzero
181 This is a bit-mask of flags that modify the way in which
187 .BR path_resolution (7)
188 for background information.)
190 The primary use case for these flags is to allow trusted programs to restrict
191 how untrusted paths (or paths inside untrusted directories) are resolved.
198 .\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0
199 Do not permit the path resolution to succeed if any component of the resolution
200 is not a descendant of the directory indicated by
202 This causes absolute symbolic links (and absolute values of
206 Currently, this flag also disables magic-link resolution (see below).
207 However, this may change in the future.
208 Therefore, to ensure that magic links are not resolved,
209 the caller should explicitly specify
210 .BR RESOLVE_NO_MAGICLINKS .
213 .\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994
214 Treat the directory referred to by
216 as the root directory while resolving
218 Absolute symbolic links are interpreted relative to
220 If a prefix component of
224 then an immediately following
226 component likewise equates to
230 is traditionally equivalent to
234 is an absolute path, it is also interpreted relative to
237 The effect of this flag is as though the calling process had used
239 to (temporarily) modify its root directory (to the directory
244 (which changes the filesystem root permanently for a process),
246 allows a program to efficiently restrict path resolution on a per-open basis.
248 Currently, this flag also disables magic-link resolution.
249 However, this may change in the future.
250 Therefore, to ensure that magic links are not resolved,
251 the caller should explicitly specify
252 .BR RESOLVE_NO_MAGICLINKS .
254 .B RESOLVE_NO_MAGICLINKS
255 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
256 Disallow all magic-link resolution during path resolution.
258 Magic links are symbolic link-like objects that are most notably found in
263 .IR /proc/[pid]/fd/* .
268 Unknowingly opening magic links can be risky for some applications.
269 Examples of such risks include the following:
272 If the process opening a pathname is a controlling process that
273 currently has no controlling terminal (see
274 .BR credentials (7)),
275 then opening a magic link inside
277 that happens to refer to a terminal
278 would cause the process to acquire a controlling terminal.
280 .\" From https://lwn.net/Articles/796868/:
281 .\" The presence of this flag will prevent a path lookup operation
282 .\" from traversing through one of these magic links, thus blocking
283 .\" (for example) attempts to escape from a container via a /proc
284 .\" entry for an open file descriptor.
285 In a containerized environment,
288 may refer to an object outside the container,
289 and thus may provide a means to escape from the container.
292 Because of such risks,
293 an application may prefer to disable magic link resolution using the
294 .BR RESOLVE_NO_MAGICLINKS
297 If the trailing component (i.e., basename) of
302 .BR RESOLVE_NO_MAGICLINKS ,
311 file descriptor referencing the magic link will be returned.
313 .B RESOLVE_NO_SYMLINKS
314 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
315 Disallow resolution of symbolic links during path resolution.
317 .BR RESOLVE_NO_MAGICLINKS .
319 If the trailing component (i.e., basename) of
324 .BR RESOLVE_NO_SYMLINKS ,
333 file descriptor referencing the symbolic link will be returned.
335 Note that the effect of the
336 .BR RESOLVE_NO_SYMLINKS
338 which affects the treatment of symbolic links in all of the components of
340 differs from the effect of the
342 file creation flag (in
344 which affects the handling of symbolic links only in the final component of
347 Applications that employ the
348 .BR RESOLVE_NO_SYMLINKS
349 flag are encouraged to make its use configurable
350 (unless it is used for a specific security purpose),
351 as symbolic links are very widely used by end-users.
352 Setting this flag indiscriminately\(emi.e.,
353 for purposes not specifically related to security\(emfor all uses of
355 may result in spurious errors on previously functional systems.
356 This may occur if, for example,
357 a system pathname that is used by an application is modified
358 (e.g., in a new distribution release)
359 so that a pathname component (now) contains a symbolic link.
362 .\" commit 72ba29297e1439efaa54d9125b866ae9d15df339
363 Disallow traversal of mount points during path resolution (including all bind
367 must either be on the same mount as the directory referred to by
369 or on the same mount as the current working directory if
374 Applications that employ the
376 flag are encouraged to make its use configurable (unless it is
377 used for a specific security purpose),
378 as bind mounts are widely used by end-users.
379 Setting this flag indiscriminately\(emi.e.,
380 for purposes not specifically related to security\(emfor all uses of
382 may result in spurious errors on previously functional systems.
383 This may occur if, for example,
384 a system pathname that is used by an application is modified
385 (e.g., in a new distribution release)
386 so that a pathname component (now) contains a bind mount.
389 Make the open operation fail unless all path components are already present
390 in the kernel's lookup cache.
391 If any kind of revalidation or I/O is needed to satisfy the lookup,
395 This is useful in providing a fast-path open that can be performed without
396 resorting to thread offload, or other mechanisms that an application might
397 use to offload slower operations.
400 If any bits other than those listed above are set in
402 an error is returned.
404 On success, a new file descriptor is returned.
405 On error, \-1 is returned, and
407 is set to indicate the error.
409 The set of errors returned by
411 includes all of the errors returned by
413 as well as the following additional errors:
416 An extension that this kernel does not support was specified in
418 (See the "Extensibility" section of
420 for more detail on how extensions are handled.)
427 .BR RESOLVE_BENEATH ,
428 and the kernel could not ensure that a ".." component didn't escape (due to a
429 race condition or potential attack).
430 The caller may choose to retry the
436 was set, and the open operation cannot be performed using only cached
437 information. The caller should retry without
443 An unknown flag or invalid value was specified in
457 was smaller than any known version of
458 .IR "struct open_how" .
463 .BR RESOLVE_NO_SYMLINKS ,
464 and one of the path components was a symbolic link (or magic link).
469 .BR RESOLVE_NO_MAGICLINKS ,
470 and one of the path components was a magic link.
477 .BR RESOLVE_BENEATH ,
478 and an escape from the root during path resolution was detected.
483 .BR RESOLVE_NO_XDEV ,
484 and a path component crosses a mount point.
487 first appeared in Linux 5.6.
488 .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179
490 This system call is Linux-specific.
494 were modeled after FreeBSD's
497 Glibc does not provide a wrapper for this system call; call it using
501 In order to allow for future extensibility,
503 requires the user-space application to specify the size of the
505 structure that it is passing.
506 By providing this information, it is possible for
508 to provide both forwards- and backwards-compatibility, with
510 acting as an implicit version number.
511 (Because new extension fields will always
512 be appended, the structure size will always increase.)
513 This extensibility design is very similar to other system calls such as
514 .BR sched_setattr (2),
515 .BR perf_event_open (2),
521 be the size of the structure as specified by the user-space application, and
523 be the size of the structure which the kernel supports, then there are
524 three cases to consider:
530 then there is no version mismatch and
532 can be used verbatim.
538 then there are some extension fields that the kernel supports
539 which the user-space application
541 Because a zero value in any added extension field signifies a no-op,
543 treats all of the extension fields not provided by the user-space application
544 as having zero values.
545 This provides backwards-compatibility.
551 then there are some extension fields which the user-space application
552 is aware of but which the kernel does not support.
553 Because any extension field must have its zero values signify a no-op,
555 safely ignore the unsupported extension fields if they are all-zero.
556 If any unsupported extension fields are nonzero, then \-1 is returned and
560 This provides forwards-compatibility.
562 Because the definition of
564 may change in the future (with new fields being added when system headers are
565 updated), user-space applications should zero-fill
567 to ensure that recompiling the program with new headers will not result in
568 spurious errors at runtime.
569 The simplest way is to use a designated
574 struct open_how how = { .flags = O_RDWR,
575 .resolve = RESOLVE_IN_ROOT };
586 memset(&how, 0, sizeof(how));
588 how.resolve = RESOLVE_IN_ROOT;
592 A user-space application that wishes to determine which extensions
593 the running kernel supports can do so by conducting a binary search on
595 with a structure which has every byte nonzero (to find the largest value
596 which doesn't produce an error of
600 .BR path_resolution (7),