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

Add manual pages to document the move_mount() system call.

Signed-off-by: David Howells <>

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

diff --git a/man2/move_mount.2 b/man2/move_mount.2
new file mode 100644
index 000000000..2ceb775d9
--- /dev/null
+++ b/man2/move_mount.2
@@ -0,0 +1,267 @@
+'\" 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 MOVE_MOUNT 2 2020-08-24 "Linux" "Linux Programmer's Manual"
+move_mount \- Move mount objects around the filesystem topology
+.B #include <sys/types.h>
+.B #include <sys/mount.h>
+.B #include <unistd.h>
+.BR "#include <fcntl.h>           " "/* Definition of AT_* constants */"
+.BI "int move_mount(int " from_dirfd ", const char *" from_pathname ","
+.BI "               int " to_dirfd ", const char *" to_pathname ","
+.BI "               unsigned int " flags );
+.IR Note :
+There is no glibc wrapper for this system call.
+.BR move_mount ()
+call moves a mount from one place to another; it can also be used to attach an
+unattached mount that was created by
+.BR fsmount "() or " open_tree "() with " OPEN_TREE_CLONE .
+.BR move_mount ()
+is called repeatedly with a file descriptor that refers to a mount object,
+then the object will be attached/moved the first time and then moved
+repeatedly, detaching it from the previous mountpoint each time.
+To access the source mount object or the destination mountpoint, no
+permissions are required on the object itself, but if either pathname is
+supplied, execute (search) permission is required on all of the directories
+specified in
+.IR from_pathname " or " to_pathname .
+The caller does, however, require the appropriate privilege (Linux: the
+capability) to move or attach mounts.
+.BR move_mount ()
+.IR from_pathname ", " from_dirfd " and part of " flags
+to locate the mount object to be moved and
+.IR to_pathname ", " to_dirfd " and another part of " flags
+to locate the destination mountpoint.  Each lookup can be done in one of a
+variety of ways:
+[*] By absolute path.
+The pathname points to an absolute path and the dirfd is ignored.  The file is
+looked up by name, starting from the root of the filesystem as seen by the
+calling process.
+[*] By cwd-relative path.
+The pathname points to a relative path and the dirfd is
+The file is looked up by name, starting from the current working directory.
+[*] By dir-relative path.
+The pathname points to relative path and the dirfd indicates a file descriptor
+pointing to a directory.  The file is looked up by name, starting from the
+directory specified by
+.IR dirfd .
+[*] By file descriptor.  The pathname is an empty string (""), the dirfd
+points directly to the mount object to move or the destination mount point and
+the appropriate
+flag is set.
+.I flags
+can be used to influence a path-based lookup.  The value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+.I from_pathname
+is an empty string, operate on the file referred to by
+.IR from_dirfd
+(which may have been obtained using the
+.BR open (2)
+flag or
+.BR open_tree ())
+.I from_dirfd
+the call operates on the current working directory.
+In this case,
+.I from_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.
+As above, but operating on
+.IR to_pathname " and " to_dirfd .
+Don't automount the terminal ("basename") component of
+.I from_pathname
+if it is a directory that is an automount point.  This allows a mount object
+that has an automount point at its root to be moved and prevents unintended
+triggering of an automount point.
+flag has no effect if the automount point has already been mounted over.  This
+flag is Linux-specific; define
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+As above, but operating on
+.IR to_pathname " and " to_dirfd .
+This allows an automount point to be manually mounted over.
+.I from_pathname
+is a symbolic link, then dereference it.  The default for
+.BR move_mount ()
+is to not follow symlinks.
+As above, but operating on
+.IR to_pathname " and " to_dirfd .
+On success, 0 is returned.  On error, \-1 is returned, and
+.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).)
+.IR from_dirfd " or " to_dirfd
+is not a valid open file descriptor.
+.IR from_pathname " or " to_pathname
+is NULL or either one 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.
+.IR from_pathname " or " to_pathname
+is too long.
+A component of
+.IR from_pathname " or " to_pathname
+does not exist, or one is an empty string and the appropriate
+was not specified in
+.IR flags .
+Out of memory (i.e., kernel memory).
+A component of the path prefix of
+.IR from_pathname " or " to_pathname
+is not a directory or one or the other is relative and the appropriate
+.I *_dirfd
+is a file descriptor referring to a file other than a directory.
+.BR move_mount ()
+was added to Linux in kernel 5.2.
+.BR move_mount ()
+is Linux-specific.
+Glibc does not (yet) provide a wrapper for the
+.BR move_mount ()
+system call; call it using
+.BR syscall (2).
+.BR move_mount ()
+function can be used like the following:
+move_mount(AT_FDCWD, "/a", AT_FDCWD, "/b", 0);
+This would move the object mounted on "/a" to "/b".  It can also be used in
+conjunction with
+.BR open_tree "(2) or " open "(2) with " O_PATH :
+fd = open_tree(AT_FDCWD, "/mnt", 0);
+move_mount(fd, "", AT_FDCWD, "/mnt2", MOVE_MOUNT_F_EMPTY_PATH);
+move_mount(fd, "", AT_FDCWD, "/mnt3", MOVE_MOUNT_F_EMPTY_PATH);
+move_mount(fd, "", AT_FDCWD, "/mnt4", MOVE_MOUNT_F_EMPTY_PATH);
+This would attach the path point for "/mnt" to fd, then it would move the
+mount to "/mnt2", then move it to "/mnt3" and finally to "/mnt4".
+It can also be used to attach new mounts:
+sfd = fsopen("ext4", FSOPEN_CLOEXEC);
+fsconfig(sfd, FSCONFIG_SET_STRING, "source", "/dev/sda1", 0);
+fsconfig(sfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
+fsconfig(sfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
+move_mount(mfd, "", AT_FDCWD, "/home", MOVE_MOUNT_F_EMPTY_PATH);
+Which would open the Ext4 filesystem mounted on "/dev/sda1", turn on user
+extended attribute support and create a mount object for it.  Finally, the new
+mount object would be attached with
+.BR move_mount ()
+to "/home".
+.BR fsmount (2),
+.BR fsopen (2),
+.BR open_tree (2)

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

Thread overview: 26+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-08-24 12:24 [PATCH 1/5] Add manpage for open_tree(2) David Howells
2020-08-24 12:24 ` David Howells [this message]
2020-08-27 11:04   ` [PATCH 2/5] Add manpages for move_mount(2) 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

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 2/5] Add manpages for move_mount(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).