Debian Codegraph @

upstream/debian-unstable/man2/openat2.2

raw
1 .\" Copyright 2019, Aleksa Sarai <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH openat2 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 openat2 \- open and possibly create a file (extended)
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <fcntl.h>" \
15 " /* Definition of " O_* " and " S_* " constants */"
16 .BR "#include <linux/openat2.h>" " /* Definition of " RESOLVE_* " constants */"
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .BI "long syscall(SYS_openat2, int " dirfd ", const char *" path ,
21 .BI " struct open_how *" how ", size_t " size );
22 .fi
23 .P
24 .IR Note :
25 glibc provides no wrapper for
26 .BR openat2 (),
27 necessitating the use of
28 .BR syscall (2).
29 .SH DESCRIPTION
30 The
31 .BR openat2 ()
32 system call is an extension of
33 .BR openat (2)
34 and provides a superset of its functionality.
35 .P
36 The
37 .BR openat2 ()
38 system call opens the file specified by
39 .IR path .
40 If the specified file does not exist, it may optionally (if
41 .B O_CREAT
42 is specified in
43 .IR how.flags )
44 be created.
45 .P
46 As with
47 .BR openat (2),
48 if
49 .I path
50 is relative, then it is interpreted relative to the
51 directory referred to by the file descriptor
52 .I dirfd
53 (or the current working directory of the calling process, if
54 .I dirfd
55 is the special value
56 .BR AT_FDCWD ).
57 If
58 .I path
59 is absolute, then
60 .I dirfd
61 is ignored (unless
62 .I how.resolve
63 contains
64 .BR RESOLVE_IN_ROOT ,
65 in which case
66 .I path
67 is resolved relative to
68 .IR dirfd ).
69 .P
70 Rather than taking a single
71 .I flags
72 argument, an extensible structure
73 .RI ( how )
74 is passed to allow for
75 future extensions.
76 The
77 .I size
78 argument must be specified as
79 .IR "sizeof(struct open_how)" .
80 .\"
81 .SS The open_how structure
82 The
83 .I how
84 argument specifies how
85 .I path
86 should be opened, and acts as a superset of the
87 .I flags
88 and
89 .I mode
90 arguments to
91 .BR openat (2).
92 This argument is a pointer to an
93 .I open_how
94 structure,
95 described in
96 .BR open_how (2type).
97 .P
98 Any future extensions to
99 .BR openat2 ()
100 will be implemented as new fields appended to the
101 .I open_how
102 structure,
103 with a zero value in a new field resulting in the kernel behaving
104 as though that extension field was not present.
105 Therefore, the caller
106 .I must
107 zero-fill this structure on
108 initialization.
109 (See the "Extensibility" section of the
110 .B NOTES
111 for more detail on why this is necessary.)
112 .P
113 The fields of the
114 .I open_how
115 structure are as follows:
116 .TP
117 .I flags
118 This field specifies
119 the file creation and file status flags to use when opening the file.
120 All of the
121 .B O_*
122 flags defined for
123 .BR openat (2)
124 are valid
125 .BR openat2 ()
126 flag values.
127 .IP
128 Whereas
129 .BR openat (2)
130 ignores unknown bits in its
131 .I flags
132 argument,
133 .BR openat2 ()
134 returns an error if unknown or conflicting flags are specified in
135 .IR how.flags .
136 .TP
137 .I mode
138 This field specifies the
139 mode for the new file, with identical semantics to the
140 .I mode
141 argument of
142 .BR openat (2).
143 .IP
144 Whereas
145 .BR openat (2)
146 ignores bits other than those in the range
147 .I 07777
148 in its
149 .I mode
150 argument,
151 .BR openat2 ()
152 returns an error if
153 .I how.mode
154 contains bits other than
155 .IR 07777 .
156 Similarly, an error is returned if
157 .BR openat2 ()
158 is called with a nonzero
159 .I how.mode
160 and
161 .I how.flags
162 does not contain
163 .B O_CREAT
164 or
165 .BR O_TMPFILE .
166 .TP
167 .I resolve
168 This is a bit-mask of flags that modify the way in which
169 .B all
170 components of
171 .I path
172 will be resolved.
173 (See
174 .BR path_resolution (7)
175 for background information.)
176 .IP
177 The primary use case for these flags is to allow trusted programs to restrict
178 how untrusted paths (or paths inside untrusted directories) are resolved.
179 The full list of
180 .I resolve
181 flags is as follows:
182 .RS
183 .TP
184 .B RESOLVE_BENEATH
185 .\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0
186 Do not permit the path resolution to succeed if any component of the resolution
187 is not a descendant of the directory indicated by
188 .IR dirfd .
189 This causes absolute symbolic links (and absolute values of
190 .IR path )
191 to be rejected.
192 .IP
193 Currently, this flag also disables magic-link resolution (see below).
194 However, this may change in the future.
195 Therefore, to ensure that magic links are not resolved,
196 the caller should explicitly specify
197 .BR RESOLVE_NO_MAGICLINKS .
198 .TP
199 .B RESOLVE_IN_ROOT
200 .\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994
201 Treat the directory referred to by
202 .I dirfd
203 as the root directory while resolving
204 .IR path .
205 Absolute symbolic links are interpreted relative to
206 .IR dirfd .
207 If a prefix component of
208 .I path
209 equates to
210 .IR dirfd ,
211 then an immediately following
212 .I ..\&
213 component likewise equates to
214 .I dirfd
215 (just as
216 .I /..\&
217 is traditionally equivalent to
218 .IR / ).
219 If
220 .I path
221 is absolute, it is also interpreted relative to
222 .IR dirfd .
223 .IP
224 The effect of this flag is as though the calling process had used
225 .BR chroot (2)
226 to (temporarily) modify its root directory (to the directory
227 referred to by
228 .IR dirfd ).
229 However, unlike
230 .BR chroot (2)
231 (which changes the filesystem root permanently for a process),
232 .B RESOLVE_IN_ROOT
233 allows a program to efficiently restrict path resolution on a per-open basis.
234 .IP
235 Currently, this flag also disables magic-link resolution.
236 However, this may change in the future.
237 Therefore, to ensure that magic links are not resolved,
238 the caller should explicitly specify
239 .BR RESOLVE_NO_MAGICLINKS .
240 .TP
241 .B RESOLVE_NO_MAGICLINKS
242 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
243 Disallow all magic-link resolution during path resolution.
244 .IP
245 Magic links are symbolic link-like objects that are most notably found in
246 .BR proc (5);
247 examples include
248 .IR /proc/ pid /exe
249 and
250 .IR /proc/ pid /fd/* .
251 (See
252 .BR symlink (7)
253 for more details.)
254 .IP
255 Unknowingly opening magic links can be risky for some applications.
256 Examples of such risks include the following:
257 .RS
258 .IP \[bu] 3
259 If the process opening a pathname is a controlling process that
260 currently has no controlling terminal (see
261 .BR credentials (7)),
262 then opening a magic link inside
263 .IR /proc/ pid /fd
264 that happens to refer to a terminal
265 would cause the process to acquire a controlling terminal.
266 .IP \[bu]
267 .\" From https://lwn.net/Articles/796868/:
268 .\" The presence of this flag will prevent a path lookup operation
269 .\" from traversing through one of these magic links, thus blocking
270 .\" (for example) attempts to escape from a container via a /proc
271 .\" entry for an open file descriptor.
272 In a containerized environment,
273 a magic link inside
274 .I /proc
275 may refer to an object outside the container,
276 and thus may provide a means to escape from the container.
277 .RE
278 .IP
279 Because of such risks,
280 an application may prefer to disable magic link resolution using the
281 .B RESOLVE_NO_MAGICLINKS
282 flag.
283 .IP
284 If the trailing component (i.e., basename) of
285 .I path
286 is a magic link,
287 .I how.resolve
288 contains
289 .BR RESOLVE_NO_MAGICLINKS ,
290 and
291 .I how.flags
292 contains both
293 .B O_PATH
294 and
295 .BR O_NOFOLLOW ,
296 then an
297 .B O_PATH
298 file descriptor referencing the magic link will be returned.
299 .TP
300 .B RESOLVE_NO_SYMLINKS
301 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
302 Disallow resolution of symbolic links during path resolution.
303 This option implies
304 .BR RESOLVE_NO_MAGICLINKS .
305 .IP
306 If the trailing component (i.e., basename) of
307 .I path
308 is a symbolic link,
309 .I how.resolve
310 contains
311 .BR RESOLVE_NO_SYMLINKS ,
312 and
313 .I how.flags
314 contains both
315 .B O_PATH
316 and
317 .BR O_NOFOLLOW ,
318 then an
319 .B O_PATH
320 file descriptor referencing the symbolic link will be returned.
321 .IP
322 Note that the effect of the
323 .B RESOLVE_NO_SYMLINKS
324 flag,
325 which affects the treatment of symbolic links in all of the components of
326 .IR path ,
327 differs from the effect of the
328 .B O_NOFOLLOW
329 file creation flag (in
330 .IR how.flags ),
331 which affects the handling of symbolic links only in the final component of
332 .IR path .
333 .IP
334 Applications that employ the
335 .B RESOLVE_NO_SYMLINKS
336 flag are encouraged to make its use configurable
337 (unless it is used for a specific security purpose),
338 as symbolic links are very widely used by end-users.
339 Setting this flag indiscriminately\[em]i.e.,
340 for purposes not specifically related to security\[em]for all uses of
341 .BR openat2 ()
342 may result in spurious errors on previously functional systems.
343 This may occur if, for example,
344 a system pathname that is used by an application is modified
345 (e.g., in a new distribution release)
346 so that a pathname component (now) contains a symbolic link.
347 .TP
348 .B RESOLVE_NO_XDEV
349 .\" commit 72ba29297e1439efaa54d9125b866ae9d15df339
350 Disallow traversal of mount points during path resolution (including all bind
351 mounts).
352 Consequently,
353 .I path
354 must either be on the same mount as the directory referred to by
355 .IR dirfd ,
356 or on the same mount as the current working directory if
357 .I dirfd
358 is specified as
359 .BR AT_FDCWD .
360 .IP
361 Applications that employ the
362 .B RESOLVE_NO_XDEV
363 flag are encouraged to make its use configurable (unless it is
364 used for a specific security purpose),
365 as bind mounts are widely used by end-users.
366 Setting this flag indiscriminately\[em]i.e.,
367 for purposes not specifically related to security\[em]for all uses of
368 .BR openat2 ()
369 may result in spurious errors on previously functional systems.
370 This may occur if, for example,
371 a system pathname that is used by an application is modified
372 (e.g., in a new distribution release)
373 so that a pathname component (now) contains a bind mount.
374 .TP
375 .BR RESOLVE_CACHED " (since Linux 5.12)"
376 .\" commit 99668f618062816ca7ba639b007eb145b9d3d41e
377 Make the open operation fail unless all path components are already present
378 in the kernel's lookup cache.
379 If any kind of revalidation or I/O is needed to satisfy the lookup,
380 .BR openat2 ()
381 fails with the error
382 .BR EAGAIN .
383 This is useful in providing a fast-path open that can be performed without
384 resorting to thread offload, or other mechanisms that an application might
385 use to offload slower operations.
386 .RE
387 .IP
388 If any bits other than those listed above are set in
389 .IR how.resolve ,
390 an error is returned.
391 .SH RETURN VALUE
392 On success, a new file descriptor is returned.
393 On error, \-1 is returned, and
394 .I errno
395 is set to indicate the error.
396 .SH ERRORS
397 The set of errors returned by
398 .BR openat2 ()
399 includes all of the errors returned by
400 .BR openat (2),
401 as well as the following additional errors:
402 .TP
403 .B E2BIG
404 An extension that this kernel does not support was specified in
405 .IR how .
406 (See the "Extensibility" section of
407 .B NOTES
408 for more detail on how extensions are handled.)
409 .TP
410 .B EAGAIN
411 .I how.resolve
412 contains either
413 .B RESOLVE_IN_ROOT
414 or
415 .BR RESOLVE_BENEATH ,
416 and the kernel could not ensure that a ".." component didn't escape (due to a
417 race condition or potential attack).
418 The caller may choose to retry the
419 .BR openat2 ()
420 call.
421 .TP
422 .B EAGAIN
423 .B RESOLVE_CACHED
424 was set, and the open operation cannot be performed using only cached
425 information.
426 The caller should retry without
427 .B RESOLVE_CACHED
428 set in
429 .IR how.resolve .
430 .TP
431 .B EINVAL
432 An unknown flag or invalid value was specified in
433 .IR how .
434 .TP
435 .B EINVAL
436 .I mode
437 is nonzero, but
438 .I how.flags
439 does not contain
440 .B O_CREAT
441 or
442 .BR O_TMPFILE .
443 .TP
444 .B EINVAL
445 .I size
446 was smaller than any known version of
447 .IR "struct open_how" .
448 .TP
449 .B ELOOP
450 .I how.resolve
451 contains
452 .BR RESOLVE_NO_SYMLINKS ,
453 and one of the path components was a symbolic link (or magic link).
454 .TP
455 .B ELOOP
456 .I how.resolve
457 contains
458 .BR RESOLVE_NO_MAGICLINKS ,
459 and one of the path components was a magic link.
460 .TP
461 .B EXDEV
462 .I how.resolve
463 contains either
464 .B RESOLVE_IN_ROOT
465 or
466 .BR RESOLVE_BENEATH ,
467 and an escape from the root during path resolution was detected.
468 .TP
469 .B EXDEV
470 .I how.resolve
471 contains
472 .BR RESOLVE_NO_XDEV ,
473 and a path component crosses a mount point.
474 .SH STANDARDS
475 Linux.
476 .SH HISTORY
477 Linux 5.6.
478 .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179
479 .P
480 The semantics of
481 .B RESOLVE_BENEATH
482 were modeled after FreeBSD's
483 .BR O_BENEATH ,
484 but avoided a well-known correctness bug in FreeBSD's implementation that
485 rendered it effectively insecure.
486 Later, FreeBSD 13 introduced
487 .B O_RESOLVE_BENEATH
488 to replace the insecure
489 .BR O_BENEATH .
490 .\" https://reviews.freebsd.org/D25886
491 .\" https://reviews.freebsd.org/D28907
492 FreeBSD's
493 .B O_RESOLVE_BENEATH
494 semantics are based on Linux's
495 .B RESOLVE_BENEATH
496 and the two are now functionally equivalent.
497 .SH NOTES
498 .SS Extensibility
499 In order to allow for future extensibility,
500 .BR openat2 ()
501 requires the user-space application to specify the size of the
502 .I open_how
503 structure that it is passing.
504 By providing this information, it is possible for
505 .BR openat2 ()
506 to provide both forwards- and backwards-compatibility, with
507 .I size
508 acting as an implicit version number.
509 (Because new extension fields will always
510 be appended, the structure size will always increase.)
511 This extensibility design is very similar to other system calls such as
512 .BR sched_setattr (2),
513 .BR perf_event_open (2),
514 and
515 .BR clone3 (2).
516 .P
517 If we let
518 .I usize
519 be the size of the structure as specified by the user-space application, and
520 .I ksize
521 be the size of the structure which the kernel supports, then there are
522 three cases to consider:
523 .IP \[bu] 3
524 If
525 .I ksize
526 equals
527 .IR usize ,
528 then there is no version mismatch and
529 .I how
530 can be used verbatim.
531 .IP \[bu]
532 If
533 .I ksize
534 is larger than
535 .IR usize ,
536 then there are some extension fields that the kernel supports
537 which the user-space application
538 is unaware of.
539 Because a zero value in any added extension field signifies a no-op,
540 the kernel
541 treats all of the extension fields not provided by the user-space application
542 as having zero values.
543 This provides backwards-compatibility.
544 .IP \[bu]
545 If
546 .I ksize
547 is smaller than
548 .IR usize ,
549 then there are some extension fields which the user-space application
550 is aware of but which the kernel does not support.
551 Because any extension field must have its zero values signify a no-op,
552 the kernel can
553 safely ignore the unsupported extension fields if they are all-zero.
554 If any unsupported extension fields are nonzero, then \-1 is returned and
555 .I errno
556 is set to
557 .BR E2BIG .
558 This provides forwards-compatibility.
559 .P
560 Because the definition of
561 .I struct open_how
562 may change in the future (with new fields being added when system headers are
563 updated), user-space applications should zero-fill
564 .I struct open_how
565 to ensure that recompiling the program with new headers will not result in
566 spurious errors at run time.
567 The simplest way is to use a designated
568 initializer:
569 .P
570 .in +4n
571 .EX
572 struct open_how how = { .flags = O_RDWR,
573 .resolve = RESOLVE_IN_ROOT };
574 .EE
575 .in
576 .P
577 or explicitly using
578 .BR memset (3)
579 or similar:
580 .P
581 .in +4n
582 .EX
583 struct open_how how;
584 memset(&how, 0, sizeof(how));
585 how.flags = O_RDWR;
586 how.resolve = RESOLVE_IN_ROOT;
587 .EE
588 .in
589 .P
590 A user-space application that wishes to determine which extensions
591 the running kernel supports can do so by conducting a binary search on
592 .I size
593 with a structure which has every byte nonzero (to find the largest value
594 which doesn't produce an error of
595 .BR E2BIG ).
596 .SH SEE ALSO
597 .BR openat (2),
598 .BR open_how (2type),
599 .BR path_resolution (7),
600 .BR symlink (7)