Debian Codegraph @

upstream/mageia-cauldron/man2/open_tree.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH open_tree 2 2025-12-25 "Linux man-pages 6.17"
6 .SH NAME
7 open_tree \- open path or create detached mount object and attach to fd
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */"
14 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
15 .B #include <sys/mount.h>
16 .P
17 .BI "int open_tree(int " dirfd ", const char *" path ", unsigned int " flags );
18 .P
19 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
20 .P
21 .B int syscall(SYS_open_tree_attr,
22 .BI " int " dirfd ", const char *" path ", unsigned int " flags ,
23 .BI " struct mount_attr *_Nullable " attr ", size_t " size );
24 .fi
25 .P
26 .IR Note :
27 glibc provides no wrapper for
28 .BR open_tree_attr (),
29 necessitating the use of
30 .BR syscall (2).
31 .SH DESCRIPTION
32 The
33 .BR open_tree ()
34 system call is part of
35 the suite of file-descriptor-based mount facilities in Linux.
36 .IP \[bu] 3
37 If
38 .I flags
39 contains
40 .BR \%OPEN_TREE_CLONE ,
41 .BR open_tree ()
42 creates a detached mount object
43 which consists of a bind-mount of
44 the path specified by the
45 .IR path .
46 A new file descriptor
47 associated with the detached mount object
48 is then returned.
49 The mount object is equivalent to a bind-mount
50 that would be created by
51 .BR mount (2)
52 called with
53 .BR \%MS_BIND ,
54 except that it is tied to a file descriptor
55 and is not mounted onto the filesystem.
56 .IP
57 As with file descriptors returned from
58 .BR fsmount (2),
59 the resultant file descriptor can then be used with
60 .BR move_mount (2),
61 .BR mount_setattr (2),
62 or other such system calls to do further mount operations.
63 .IP
64 This mount object will be unmounted and destroyed
65 when the file descriptor is closed
66 if it was not otherwise attached to a mount point
67 by calling
68 .BR move_mount (2).
69 This implicit unmount operation is lazy\[em]\c
70 akin to calling
71 .BR umount2 (2)
72 with
73 .BR \%MNT_DETACH ;
74 thus,
75 any existing open references to files
76 from the mount object
77 will continue to work,
78 and the mount object will only be completely destroyed
79 once it ceases to be busy.
80 .IP \[bu]
81 If
82 .I flags
83 does not contain
84 .BR \%OPEN_TREE_CLONE ,
85 .BR open_tree ()
86 returns a file descriptor
87 that is exactly equivalent to
88 one produced by
89 .BR openat (2)
90 when called with the same
91 .I dirfd
92 and
93 .IR path .
94 .P
95 In either case, the resultant file descriptor
96 acts the same as one produced by
97 .BR open (2)
98 with
99 .BR O_PATH ,
100 meaning it can also be used as a
101 .I dirfd
102 argument to
103 "*at()" system calls.
104 However,
105 unlike
106 .BR open (2)
107 called with
108 .BR O_PATH ,
109 automounts will
110 by default
111 be triggered by
112 .BR open_tree ()
113 unless
114 .B \%AT_NO_AUTOMOUNT
115 is included in
116 .IR flags .
117 .P
118 As with "*at()" system calls,
119 .BR open_tree ()
120 uses the
121 .I dirfd
122 argument in conjunction with the
123 .I path
124 argument to determine the path to operate on, as follows:
125 .IP \[bu] 3
126 If the pathname given in
127 .I path
128 is absolute, then
129 .I dirfd
130 is ignored.
131 .IP \[bu]
132 If the pathname given in
133 .I path
134 is relative and
135 .I dirfd
136 is the special value
137 .BR \%AT_FDCWD ,
138 then
139 .I path
140 is interpreted relative to
141 the current working directory
142 of the calling process (like
143 .BR open (2)).
144 .IP \[bu]
145 If the pathname given in
146 .I path
147 is relative,
148 then it is interpreted relative to
149 the directory referred to by the file descriptor
150 .I dirfd
151 (rather than relative to
152 the current working directory
153 of the calling process,
154 as is done by
155 .BR open (2)
156 for a relative pathname).
157 In this case,
158 .I dirfd
159 must be a directory
160 that was opened for reading
161 .RB ( \%O_RDONLY )
162 or using the
163 .B O_PATH
164 flag.
165 .IP \[bu]
166 If
167 .I path
168 is an empty string,
169 and
170 .I flags
171 contains
172 .BR \%AT_EMPTY_PATH ,
173 then the file descriptor
174 .I dirfd
175 is operated on directly.
176 In this case,
177 .I dirfd
178 may refer to any type of file,
179 not just a directory.
180 .P
181 See
182 .BR openat (2)
183 for an explanation of why the
184 .I dirfd
185 argument is useful.
186 .P
187 .I flags
188 can be used to control aspects of the path lookup
189 and properties of the returned file descriptor.
190 A value for
191 .I flags
192 is constructed by bitwise ORing
193 zero or more of the following constants:
194 .RS
195 .TP
196 .B \%AT_EMPTY_PATH
197 If
198 .I path
199 is an empty string, operate on the file referred to by
200 .I dirfd
201 (which may have been obtained from
202 .BR open (2),
203 .BR fsmount (2),
204 or from another
205 .BR open_tree ()
206 call).
207 In this case,
208 .I dirfd
209 may refer to any type of file, not just a directory.
210 If
211 .I dirfd
212 is
213 .BR \%AT_FDCWD ,
214 .BR open_tree ()
215 will operate on the current working directory
216 of the calling process.
217 This flag is Linux-specific;
218 define
219 .B \%_GNU_SOURCE
220 to obtain its definition.
221 .TP
222 .B \%AT_NO_AUTOMOUNT
223 Do not automount the terminal ("basename") component of
224 .I path
225 if it is a directory that is an automount point.
226 This allows you to create a handle to the automount point itself,
227 rather than the location it would mount.
228 This flag has no effect if the mount point has already been mounted over.
229 This flag is Linux-specific;
230 define
231 .B \%_GNU_SOURCE
232 to obtain its definition.
233 .TP
234 .B \%AT_SYMLINK_NOFOLLOW
235 If
236 .I path
237 is a symbolic link, do not dereference it;
238 instead,
239 create either a handle to the link itself
240 or a bind-mount of it.
241 The resultant file descriptor is indistinguishable from one produced by
242 .BR openat (2)
243 with
244 .BR \%O_PATH | O_NOFOLLLOW .
245 .TP
246 .B \%OPEN_TREE_CLOEXEC
247 Set the close-on-exec
248 .RB ( FD_CLOEXEC )
249 flag on the new file descriptor.
250 See the description of the
251 .B O_CLOEXEC
252 flag in
253 .BR open (2)
254 for reasons why this may be useful.
255 .TP
256 .B \%OPEN_TREE_CLONE
257 Rather than creating an
258 .BR openat (2)-style
259 .B O_PATH
260 file descriptor,
261 create a bind-mount of
262 .I path
263 (akin to
264 .IR \%mount\~\-\-bind )
265 as a detached mount object.
266 In order to do this operation,
267 the calling process must have the
268 .B \%CAP_SYS_ADMIN
269 capability.
270 .TP
271 .B \%AT_RECURSIVE
272 Create a recursive bind-mount of the path
273 (akin to
274 .IR \%mount\~\-\-rbind )
275 as a detached mount object.
276 This flag is only permitted in conjunction with
277 .BR \%OPEN_TREE_CLONE .
278 .SS open_tree_attr()
279 The
280 .BR open_tree_attr ()
281 system call operates in exactly the same way as
282 .BR open_tree (),
283 except for the differences described here.
284 .P
285 After performing the same operation as with
286 .BR open_tree (),
287 .BR open_tree_attr ()
288 will apply the mount attribute changes described in
289 .I attr
290 to the file descriptor before it is returned.
291 (See
292 .BR mount_attr (2type)
293 for a description of the
294 .I \%mount_attr
295 structure.
296 As described in
297 .BR mount_setattr (2),
298 .I size
299 must be set to
300 .I \%sizeof(struct mount_attr)
301 in order to support future extensions.)
302 If
303 .I attr
304 is NULL,
305 or has
306 .IR \%attr.attr_clr ,
307 .IR \%attr.attr_set ,
308 and
309 .I \%attr.propagation
310 all set to zero,
311 then
312 .BR open_tree_attr ()
313 has identical behavior to
314 .BR open_tree ().
315 .P
316 The application of
317 .I attr
318 to the resultant file descriptor
319 has identical semantics to
320 .BR mount_setattr (2),
321 except for the following extensions and general caveats:
322 .IP \[bu] 3
323 Unlike
324 .BR mount_setattr (2)
325 called with a regular
326 .B OPEN_TREE_CLONE
327 detached mount object from
328 .BR open_tree (),
329 .BR open_tree_attr ()
330 can specify a different setting for
331 .B \%MOUNT_ATTR_IDMAP
332 to the original mount object cloned with
333 .BR \%OPEN_TREE_CLONE .
334 .IP
335 Adding
336 .B \%MOUNT_ATTR_IDMAP
337 to
338 .I \%attr.attr_clr
339 will disable ID-mapping for the new mount object;
340 adding
341 .B \%MOUNT_ATTR_IDMAP
342 to
343 .I \%attr.attr_set
344 will configure the mount object to have the ID-mapping defined by
345 the user namespace referenced by the file descriptor
346 .IR \%attr.userns_fd .
347 (The semantics of which are identical to when
348 .BR mount_setattr (2)
349 is used to configure
350 .BR \%MOUNT_ATTR_IDMAP .)
351 .IP
352 Changing or removing the mapping
353 of an ID-mapped mount is only permitted
354 if a new detached mount object is being created with
355 .I flags
356 including
357 .BR \%OPEN_TREE_CLONE .
358 .\" Aleksa Sarai
359 .\" At time of writing, this is not actually true because of a bug where
360 .\" open_tree_attr() would accidentally permit changing MOUNT_ATTR_IDMAP for
361 .\" existing detached mount objects without setting OPEN_TREE_CLONE, but a
362 .\" patch to fix it has been slated for 6.18 and will be backported to 6.15+.
363 .\" <https://lore.kernel.org/r/20250808-open_tree_attr-bugfix-idmap-v1-0-0ec7bc05646c@cyphar.com/>
364 .IP \[bu]
365 If
366 .I flags
367 contains
368 .BR \%AT_RECURSIVE ,
369 then the attributes described in
370 .I attr
371 are applied recursively
372 (just as when
373 .BR mount_setattr (2)
374 is called with
375 .BR \%AT_RECURSIVE ).
376 However, this applies in addition to the
377 .BR open_tree ()-specific
378 behavior regarding
379 .BR \%AT_RECURSIVE ,
380 and thus
381 .I flags
382 must also contain
383 .BR \%OPEN_TREE_CLONE .
384 .P
385 Note that if
386 .I flags
387 does not contain
388 .BR \%OPEN_TREE_CLONE ,
389 .BR open_tree_attr ()
390 will attempt to modify the mount attributes of
391 the mount object attached at
392 the path described by
393 .I dirfd
394 and
395 .IR path .
396 As with
397 .BR mount_setattr (2),
398 if said path is not a mount point,
399 .BR open_tree_attr ()
400 will return an error.
401 .SH RETURN VALUE
402 On success, a new file descriptor is returned.
403 On error, \-1 is returned, and
404 .I errno
405 is set to indicate the error.
406 .SH ERRORS
407 .TP
408 .B EACCES
409 Search permission is denied for one of the directories
410 in the path prefix of
411 .IR path .
412 (See also
413 .BR path_resolution (7).)
414 .TP
415 .B EBADF
416 .I path
417 is relative but
418 .I dirfd
419 is neither
420 .B \%AT_FDCWD
421 nor a valid file descriptor.
422 .TP
423 .B EFAULT
424 .I path
425 is NULL
426 or a pointer to a location
427 outside the calling process's accessible address space.
428 .TP
429 .B EINVAL
430 Invalid flag specified in
431 .IR flags .
432 .TP
433 .B ELOOP
434 Too many symbolic links encountered when resolving
435 .IR path .
436 .TP
437 .B EMFILE
438 The calling process has too many open files to create more.
439 .TP
440 .B ENAMETOOLONG
441 .I path
442 is longer than
443 .BR PATH_MAX .
444 .TP
445 .B ENFILE
446 The system has too many open files to create more.
447 .TP
448 .B ENOENT
449 A component of
450 .I path
451 does not exist, or is a dangling symbolic link.
452 .TP
453 .B ENOENT
454 .I path
455 is an empty string, but
456 .B AT_EMPTY_PATH
457 is not specified in
458 .IR flags .
459 .TP
460 .B ENOTDIR
461 A component of the path prefix of
462 .I path
463 is not a directory, or
464 .I path
465 is relative and
466 .I dirfd
467 is a file descriptor referring to a file other than a directory.
468 .TP
469 .B ENOSPC
470 The "anonymous" mount namespace
471 necessary to contain the
472 .B \%OPEN_TREE_CLONE
473 detached bind-mount mount object
474 could not be allocated,
475 as doing so would exceed
476 the configured per-user limit on
477 the number of mount namespaces in the current user namespace.
478 (See also
479 .BR namespaces (7).)
480 .TP
481 .B ENOMEM
482 The kernel could not allocate sufficient memory to complete the operation.
483 .TP
484 .B EPERM
485 .I flags
486 contains
487 .B \%OPEN_TREE_CLONE
488 but the calling process does not have the required
489 .B CAP_SYS_ADMIN
490 capability.
491 .SH STANDARDS
492 Linux.
493 .SH HISTORY
494 .SS open_tree()
495 Linux 5.2.
496 .\" commit a07b20004793d8926f78d63eb5980559f7813404
497 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
498 glibc 2.36.
499 .SS open_tree_attr()
500 Linux 6.15.
501 .\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8
502 .\" commit 7a54947e727b6df840780a66c970395ed9734ebe
503 .SH NOTES
504 .SS Mount propagation
505 The bind-mount mount objects created by
506 .BR open_tree ()
507 with
508 .B \%OPEN_TREE_CLONE
509 are not associated with
510 the mount namespace of the calling process.
511 Instead, each mount object is placed
512 in a newly allocated "anonymous" mount namespace
513 associated with the calling process.
514 .P
515 One of the side-effects of this is that
516 (unlike bind-mounts created with
517 .BR mount (2)),
518 mount propagation
519 (as described in
520 .BR mount_namespaces (7))
521 will not be applied to bind-mounts created by
522 .BR open_tree ()
523 until the bind-mount is attached with
524 .BR move_mount (2),
525 at which point the mount object
526 will be associated with the mount namespace
527 where it was attached
528 and mount propagation will resume.
529 Note that any mount propagation events that occurred
530 before the mount object was attached
531 will
532 .I not
533 be propagated to the mount object,
534 even after it is attached.
535 .SH EXAMPLES
536 The following examples show how
537 .BR open_tree ()
538 can be used in place of more traditional
539 .BR mount (2)
540 calls with
541 .BR MS_BIND .
542 .P
543 .in +4n
544 .EX
545 int srcfd = open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE);
546 move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
547 .EE
548 .in
549 .P
550 First,
551 a detached bind-mount mount object of
552 .I /var
553 is created
554 and associated with the file descriptor
555 .IR srcfd .
556 Then, the mount object is attached to
557 .I /mnt
558 using
559 .BR move_mount (2)
560 with
561 .B \%MOVE_MOUNT_F_EMPTY_PATH
562 to request that the detached mount object
563 associated with the file descriptor
564 .I srcfd
565 be moved (and thus attached) to
566 .IR /mnt .
567 .P
568 The above procedure is functionally equivalent to
569 the following mount operation using
570 .BR mount (2):
571 .P
572 .in +4n
573 .EX
574 mount("/var", "/mnt", NULL, MS_BIND, NULL);
575 .EE
576 .in
577 .P
578 .B \%OPEN_TREE_CLONE
579 can be combined with
580 .B \%AT_RECURSIVE
581 to create recursive detached bind-mount mount objects,
582 which in turn can be attached to mount points
583 to create recursive bind-mounts.
584 .P
585 .in +4n
586 .EX
587 int srcfd = open_tree(AT_FDCWD, "/var",
588 OPEN_TREE_CLONE | AT_RECURSIVE);
589 move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
590 .EE
591 .in
592 .P
593 The above procedure is functionally equivalent to
594 the following mount operation using
595 .BR mount (2):
596 .P
597 .in +4n
598 .EX
599 mount("/var", "/mnt", NULL, MS_BIND | MS_REC, NULL);
600 .EE
601 .in
602 .P
603 One of the primary benefits of using
604 .BR open_tree ()
605 and
606 .BR move_mount (2)
607 over the traditional
608 .BR mount (2)
609 is that operating with
610 .IR dirfd -style
611 file descriptors is far easier and more intuitive.
612 .P
613 .in +4n
614 .EX
615 int srcfd = open_tree(100, "", AT_EMPTY_PATH | OPEN_TREE_CLONE);
616 move_mount(srcfd, "", 200, "foo", MOVE_MOUNT_F_EMPTY_PATH);
617 .EE
618 .in
619 .P
620 The above procedure is roughly equivalent to
621 the following mount operation using
622 .BR mount (2):
623 .P
624 .in +4n
625 .EX
626 mount("/proc/self/fd/100",
627 "/proc/self/fd/200/foo",
628 NULL, MS_BIND, NULL);
629 .EE
630 .in
631 .P
632 In addition, you can use the file descriptor returned by
633 .BR open_tree ()
634 as the
635 .I dirfd
636 argument to any "*at()" system calls:
637 .P
638 .in +4n
639 .EX
640 int dirfd, fd;
641 \&
642 dirfd = open_tree(AT_FDCWD, "/etc", OPEN_TREE_CLONE);
643 fd = openat(dirfd, "passwd", O_RDONLY);
644 fchmodat(dirfd, "shadow", 0000, 0);
645 close(dirfd);
646 close(fd);
647 /* The bind-mount is now destroyed */
648 .EE
649 .in
650 .SS open_tree_attr()
651 The following is an example of how
652 .BR open_tree_attr ()
653 can be used to
654 take an existing id-mapped mount and
655 construct a new bind-mount mount object
656 with a different
657 .B \%MOUNT_ATTR_IDMAP
658 attribute.
659 The resultant detached mount object
660 can be used
661 like any other mount object
662 returned by
663 .BR open_tree ().
664 .P
665 .in +4n
666 .EX
667 int nsfd1, nsfd2;
668 int mntfd1, mntfd2, mntfd3;
669 struct mount_attr attr;
670 mntfd1 = open_tree(AT_FDCWD, "/foo", OPEN_TREE_CLONE);
671 \&
672 /* Configure the id-mapping of mntfd1 */
673 nsfd1 = open("/proc/1234/ns/user", O_RDONLY);
674 memset(&attr, 0, sizeof(attr));
675 attr.attr_set = MOUNT_ATTR_IDMAP;
676 attr.userns_fd = nsfd1;
677 mount_setattr(mntfd1, "", AT_EMPTY_PATH, &attr, sizeof(attr));
678 \&
679 /* Create a new copy with a different id-mapping */
680 nsfd2 = open("/proc/5678/ns/user", O_RDONLY);
681 memset(&attr, 0, sizeof(attr));
682 attr.attr_clr = MOUNT_ATTR_IDMAP;
683 .\" Using .attr_clr is not strictly necessary but makes the intent clearer.
684 attr.attr_set = MOUNT_ATTR_IDMAP;
685 attr.userns_fd = nsfd2;
686 mntfd2 = open_tree_attr(mntfd1, "", OPEN_TREE_CLONE,
687 &attr, sizeof(attr));
688 \&
689 /* Create a new copy with the id-mapping cleared */
690 memset(&attr, 0, sizeof(attr));
691 attr.attr_clr = MOUNT_ATTR_IDMAP;
692 mntfd3 = open_tree_attr(mntfd1, "", OPEN_TREE_CLONE,
693 &attr, sizeof(attr));
694 .EE
695 .in
696 .P
697 .BR open_tree_attr ()
698 can also be used
699 with attached mount objects;
700 the above example is only intended to be illustrative.
701 .SH SEE ALSO
702 .BR fsconfig (2),
703 .BR fsmount (2),
704 .BR fsopen (2),
705 .BR fspick (2),
706 .BR mount (2),
707 .BR mount_setattr (2),
708 .BR move_mount (2),
709 .BR mount_namespaces (7)