Debian Codegraph @

upstream/debian-unstable/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 2026-02-22 "Linux man-pages 6.18"
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 .TP
495 .BR open_tree ()
496 Linux 5.2,
497 .\" commit a07b20004793d8926f78d63eb5980559f7813404
498 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
499 glibc 2.36.
500 .TP
501 .BR open_tree_attr ()
502 Linux 6.15.
503 .\" commit c4a16820d90199409c9bf01c4f794e1e9e8d8fd8
504 .\" commit 7a54947e727b6df840780a66c970395ed9734ebe
505 .SH NOTES
506 .SS Mount propagation
507 The bind-mount mount objects created by
508 .BR open_tree ()
509 with
510 .B \%OPEN_TREE_CLONE
511 are not associated with
512 the mount namespace of the calling process.
513 Instead, each mount object is placed
514 in a newly allocated "anonymous" mount namespace
515 associated with the calling process.
516 .P
517 One of the side-effects of this is that
518 (unlike bind-mounts created with
519 .BR mount (2)),
520 mount propagation
521 (as described in
522 .BR mount_namespaces (7))
523 will not be applied to bind-mounts created by
524 .BR open_tree ()
525 until the bind-mount is attached with
526 .BR move_mount (2),
527 at which point the mount object
528 will be associated with the mount namespace
529 where it was attached
530 and mount propagation will resume.
531 Note that any mount propagation events that occurred
532 before the mount object was attached
533 will
534 .I not
535 be propagated to the mount object,
536 even after it is attached.
537 .SH EXAMPLES
538 The following examples show how
539 .BR open_tree ()
540 can be used in place of more traditional
541 .BR mount (2)
542 calls with
543 .BR MS_BIND .
544 .P
545 .in +4n
546 .EX
547 int srcfd = open_tree(AT_FDCWD, "/var", OPEN_TREE_CLONE);
548 move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
549 .EE
550 .in
551 .P
552 First,
553 a detached bind-mount mount object of
554 .I /var
555 is created
556 and associated with the file descriptor
557 .IR srcfd .
558 Then, the mount object is attached to
559 .I /mnt
560 using
561 .BR move_mount (2)
562 with
563 .B \%MOVE_MOUNT_F_EMPTY_PATH
564 to request that the detached mount object
565 associated with the file descriptor
566 .I srcfd
567 be moved (and thus attached) to
568 .IR /mnt .
569 .P
570 The above procedure is functionally equivalent to
571 the following mount operation using
572 .BR mount (2):
573 .P
574 .in +4n
575 .EX
576 mount("/var", "/mnt", NULL, MS_BIND, NULL);
577 .EE
578 .in
579 .P
580 .B \%OPEN_TREE_CLONE
581 can be combined with
582 .B \%AT_RECURSIVE
583 to create recursive detached bind-mount mount objects,
584 which in turn can be attached to mount points
585 to create recursive bind-mounts.
586 .P
587 .in +4n
588 .EX
589 int srcfd = open_tree(AT_FDCWD, "/var",
590 OPEN_TREE_CLONE | AT_RECURSIVE);
591 move_mount(srcfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
592 .EE
593 .in
594 .P
595 The above procedure is functionally equivalent to
596 the following mount operation using
597 .BR mount (2):
598 .P
599 .in +4n
600 .EX
601 mount("/var", "/mnt", NULL, MS_BIND | MS_REC, NULL);
602 .EE
603 .in
604 .P
605 One of the primary benefits of using
606 .BR open_tree ()
607 and
608 .BR move_mount (2)
609 over the traditional
610 .BR mount (2)
611 is that operating with
612 .IR dirfd -style
613 file descriptors is far easier and more intuitive.
614 .P
615 .in +4n
616 .EX
617 int srcfd = open_tree(100, "", AT_EMPTY_PATH | OPEN_TREE_CLONE);
618 move_mount(srcfd, "", 200, "foo", MOVE_MOUNT_F_EMPTY_PATH);
619 .EE
620 .in
621 .P
622 The above procedure is roughly equivalent to
623 the following mount operation using
624 .BR mount (2):
625 .P
626 .in +4n
627 .EX
628 mount("/proc/self/fd/100",
629 "/proc/self/fd/200/foo",
630 NULL, MS_BIND, NULL);
631 .EE
632 .in
633 .P
634 In addition, you can use the file descriptor returned by
635 .BR open_tree ()
636 as the
637 .I dirfd
638 argument to any "*at()" system calls:
639 .P
640 .in +4n
641 .EX
642 int dirfd, fd;
643 \&
644 dirfd = open_tree(AT_FDCWD, "/etc", OPEN_TREE_CLONE);
645 fd = openat(dirfd, "passwd", O_RDONLY);
646 fchmodat(dirfd, "shadow", 0000, 0);
647 close(dirfd);
648 close(fd);
649 /* The bind-mount is now destroyed */
650 .EE
651 .in
652 .SS open_tree_attr()
653 The following is an example of how
654 .BR open_tree_attr ()
655 can be used to
656 take an existing id-mapped mount and
657 construct a new bind-mount mount object
658 with a different
659 .B \%MOUNT_ATTR_IDMAP
660 attribute.
661 The resultant detached mount object
662 can be used
663 like any other mount object
664 returned by
665 .BR open_tree ().
666 .P
667 .in +4n
668 .EX
669 int nsfd1, nsfd2;
670 int mntfd1, mntfd2, mntfd3;
671 struct mount_attr attr;
672 mntfd1 = open_tree(AT_FDCWD, "/foo", OPEN_TREE_CLONE);
673 \&
674 /* Configure the id-mapping of mntfd1 */
675 nsfd1 = open("/proc/1234/ns/user", O_RDONLY);
676 memset(&attr, 0, sizeof(attr));
677 attr.attr_set = MOUNT_ATTR_IDMAP;
678 attr.userns_fd = nsfd1;
679 mount_setattr(mntfd1, "", AT_EMPTY_PATH, &attr, sizeof(attr));
680 \&
681 /* Create a new copy with a different id-mapping */
682 nsfd2 = open("/proc/5678/ns/user", O_RDONLY);
683 memset(&attr, 0, sizeof(attr));
684 attr.attr_clr = MOUNT_ATTR_IDMAP;
685 .\" Using .attr_clr is not strictly necessary but makes the intent clearer.
686 attr.attr_set = MOUNT_ATTR_IDMAP;
687 attr.userns_fd = nsfd2;
688 mntfd2 = open_tree_attr(mntfd1, "", OPEN_TREE_CLONE,
689 &attr, sizeof(attr));
690 \&
691 /* Create a new copy with the id-mapping cleared */
692 memset(&attr, 0, sizeof(attr));
693 attr.attr_clr = MOUNT_ATTR_IDMAP;
694 mntfd3 = open_tree_attr(mntfd1, "", OPEN_TREE_CLONE,
695 &attr, sizeof(attr));
696 .EE
697 .in
698 .P
699 .BR open_tree_attr ()
700 can also be used
701 with attached mount objects;
702 the above example is only intended to be illustrative.
703 .SH SEE ALSO
704 .BR fsconfig (2),
705 .BR fsmount (2),
706 .BR fsopen (2),
707 .BR fspick (2),
708 .BR mount (2),
709 .BR mount_setattr (2),
710 .BR move_mount (2),
711 .BR mount_namespaces (7)