Linux-Fsdevel Archive on
help / color / mirror / Atom feed
From: David Howells <>
Subject: [PATCH 1/5] Add manpage for open_tree(2)
Date: Mon, 24 Aug 2020 13:24:42 +0100	[thread overview]
Message-ID: <> (raw)

Add a manual page to document the open_tree() system call.

Signed-off-by: David Howells <>

 man2/open_tree.2 |  249 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 249 insertions(+)
 create mode 100644 man2/open_tree.2

diff --git a/man2/open_tree.2 b/man2/open_tree.2
new file mode 100644
index 000000000..d480bd82f
--- /dev/null
+++ b/man2/open_tree.2
@@ -0,0 +1,249 @@
+'\" t
+.\" Copyright (c) 2020 David Howells <>
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.TH OPEN_TREE 2 2020-08-24 "Linux" "Linux Programmer's Manual"
+open_tree \- Pick or clone mount object and attach to fd
+.B #include <sys/types.h>
+.B #include <sys/mount.h>
+.B #include <unistd.h>
+.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BI "int open_tree(int " dirfd ", const char *" pathname ", unsigned int " flags );
+.IR Note :
+There are no glibc wrappers for these system calls.
+.BR open_tree ()
+picks the mount object specified by the pathname and attaches it to a new file
+descriptor or clones it and attaches the clone to the file descriptor.  The
+resultant file descriptor is indistinguishable from one produced by
+.BR open "(2) with " O_PATH .
+In the case that the mount object is cloned, the clone will be "unmounted" and
+destroyed when the file descriptor is closed if it is not otherwise mounted
+somewhere by calling
+.BR move_mount (2).
+To select a mount object, no permissions are required on the object referred
+to by the path, but execute (search) permission is required on all of the
+directories in
+.I pathname
+that lead to the object.
+Appropriate privilege (Linux: the
+capability) is required to clone mount objects.
+.BR open_tree ()
+.IR pathname ", " dirfd " and " flags
+to locate the target object in one of a variety of ways:
+[*] By absolute path.
+.I pathname
+points to an absolute path and
+.I dirfd
+is ignored.  The object is looked up by name, starting from the root of the
+filesystem as seen by the calling process.
+[*] By cwd-relative path.
+.I pathname
+points to a relative path and
+.IR dirfd " is " AT_FDCWD .
+The object is looked up by name, starting from the current working directory.
+[*] By dir-relative path.
+.I pathname
+points to relative path and
+.I dirfd
+indicates a file descriptor pointing to a directory.  The object is looked up
+by name, starting from the directory specified by
+.IR dirfd .
+[*] By file descriptor.
+.I pathname
+is "",
+.I dirfd
+indicates a file descriptor and
+is set in
+.IR flags .
+The mount attached to the file descriptor is queried directly.  The file
+descriptor may point to any type of file, not just a directory.
+.I flags
+can be used to control the operation of the function and to influence a
+path-based lookup.  A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+.I pathname
+is an empty string, operate on the file referred to by
+.IR dirfd
+(which may have been obtained from
+.BR open "(2) with"
+.BR O_PATH ", from " fsmount (2)
+or from another
+.BR open_tree ()).
+.I dirfd
+the call operates on the current working directory.
+In this case,
+.I dirfd
+can refer to any type of file, not just a directory.
+This flag is Linux-specific; define
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+Don't automount the final ("basename") component of
+.I pathname
+if it is a directory that is an automount point.  This flag allows the
+automount point itself to be picked up or a mount cloned that is rooted on the
+automount point.  The
+flag has no effect if the mount point has already been mounted over.
+This flag is Linux-specific; define
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.I pathname
+is a symbolic link, do not dereference it: instead pick up or clone a mount
+rooted on the link itself.
+Set the close-on-exec flag for the new file descriptor.  This will cause the
+file descriptor to be closed automatically when a process exec's.
+Rather than directly attaching the selected object to the file descriptor,
+clone the object, set the root of the new mount object to that point and
+attach the clone to the file descriptor.
+This is only permitted in conjunction with OPEN_TREE_CLONE.  It causes the
+entire mount subtree rooted at the selected spot to be cloned rather than just
+that one mount object.
+On success, the new file descriptor is returned.  On error, \-1 is returned,
+.I errno
+is set appropriately.
+Search permission is denied for one of the directories
+in the path prefix of
+.IR pathname .
+(See also
+.BR path_resolution (7).)
+.I dirfd
+is not a valid open file descriptor.
+.I pathname
+is NULL or
+.IR pathname
+point to a location outside the process's accessible address space.
+Reserved flag specified in
+.IR flags .
+Too many symbolic links encountered while traversing the pathname.
+.I pathname
+is too long.
+A component of
+.I pathname
+does not exist, or
+.I pathname
+is an empty string and
+was not specified in
+.IR flags .
+Out of memory (i.e., kernel memory).
+A component of the path prefix of
+.I pathname
+is not a directory or
+.I pathname
+is relative and
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.BR open_tree ()
+was added to Linux in kernel 5.2.
+.BR open_tree ()
+is Linux-specific.
+Glibc does not (yet) provide a wrapper for the
+.BR open_tree ()
+system call; call it using
+.BR syscall (2).
+.BR open_tree ()
+function can be used like the following:
+fd1 = open_tree(AT_FDCWD, "/mnt", 0);
+fd2 = open_tree(fd1, "",
+move_mount(fd2, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH);
+This would attach the path point for "/mnt" to fd1, then it would copy the
+entire subtree at the point referred to by fd1 and attach that to fd2; lastly,
+it would attach the clone to "/mnt2".
+.BR fsmount (2),
+.BR move_mount (2),
+.BR open (2)

             reply	other threads:[~2020-08-24 12:26 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-24 12:24 David Howells [this message]
2020-08-24 12:24 ` [PATCH 2/5] Add manpages for move_mount(2) David Howells
2020-08-27 11:04   ` Michael Kerrisk (man-pages)
2021-08-13  0:21     ` Michael Kerrisk (man-pages)
2021-01-22  8:39   ` Michael Kerrisk (man-pages)
2020-08-24 12:24 ` [PATCH 3/5] Add manpage for fspick(2) David Howells
2020-08-27 11:05   ` Michael Kerrisk (man-pages)
2021-08-13  0:22     ` Michael Kerrisk (man-pages)
2021-01-22  8:40   ` Michael Kerrisk (man-pages)
2020-08-24 12:25 ` [PATCH 4/5] Add manpage for fsopen(2) and fsmount(2) David Howells
2020-08-27 11:07   ` Michael Kerrisk (man-pages)
2021-08-13  0:22     ` Michael Kerrisk (man-pages)
2020-09-02 15:01   ` Michael Kerrisk (man-pages)
2020-09-02 16:14   ` David Howells
2020-09-02 20:14     ` Michael Kerrisk (man-pages)
2020-09-11 12:44       ` Michael Kerrisk (man-pages)
2020-10-16  6:50         ` Michael Kerrisk (man-pages)
2021-01-22  8:41           ` Michael Kerrisk (man-pages)
2020-08-24 12:25 ` [PATCH 5/5] Add manpage for fsconfig(2) David Howells
2020-08-27 11:07   ` Michael Kerrisk (man-pages)
2021-08-13  0:23     ` Michael Kerrisk (man-pages)
2021-01-22  8:40   ` Michael Kerrisk (man-pages)
2020-08-27 11:01 ` [PATCH 1/5] Add manpage for open_tree(2) Michael Kerrisk (man-pages)
2021-01-22  8:39   ` Michael Kerrisk (man-pages)
2021-08-13  0:20   ` Michael Kerrisk (man-pages)
2021-02-25 19:03 ` Aurélien Aptel
  -- strict thread matches above, loose matches on Subject: below --
2020-08-07 14:02 David Howells
2020-08-22 20:01 ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \
    --subject='Re: [PATCH 1/5] Add manpage for open_tree(2)' \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).