Re: [PATCH 2/5] Add manpages for move_mount(2) and open_tree(2)
On 8/24/20 12:08 PM, David Howells wrote: > Michael Kerrisk (man-pages) wrote: > >>> +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 . >>> +.PP >>> +The caller does, however, require the appropriate capabilities or >>> permission >>> +to effect a mount. >> >> Maybe better: s/effect/create/ > > The mount has already been created. We're moving/attaching it. Ahh -- then the verb was wrong. to effect == to cause, bring about to affect == to change, have an impact on > Maybe: > > The caller does, however, require the appropriate privilege (Linux: > the CAP_SYS_ADMIN capability) to move or attach mounts. Yes, better. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH 2/5] Add manpages for move_mount(2) and open_tree(2)
Michael Kerrisk (man-pages) wrote: > > +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 . > > +.PP > > +The caller does, however, require the appropriate capabilities or > > permission > > +to effect a mount. > > Maybe better: s/effect/create/ The mount has already been created. We're moving/attaching it. Maybe: The caller does, however, require the appropriate privilege (Linux: the CAP_SYS_ADMIN capability) to move or attach mounts. David
Re: [PATCH 2/5] Add manpages for move_mount(2) and open_tree(2)
Hello David,
On Fri, 7 Aug 2020 at 16:02, David Howells wrote:
>
> Add manual pages to document the move_mount and open_tree() system calls.
Notwithstanding the title and the commit message, this patch documents
just move_mount(). Could you revise the title and commit message for
the next iteration please.
> Signed-off-by: David Howells
> ---
>
> man2/move_mount.2 | 275
> +
> 1 file changed, 275 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 0..aae9013fa
> --- /dev/null
> +++ b/man2/move_mount.2
> @@ -0,0 +1,275 @@
> +'\" t
> +.\" Copyright (c) 2020 David Howells
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" 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.
> +.\" %%%LICENSE_END
> +.\"
> +.TH MOVE_MOUNT 2 2020-08-07 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +move_mount \- Move mount objects around the filesystem topology
> +.SH SYNOPSIS
> +.nf
> +.B #include
> +.br
Delete the previous line (".br), and the same below (twice).
> +.B #include
> +.br
> +.B #include
> +.br
> +.BR "#include" "/* Definition of AT_* constants */"
> +.PP
> +.BI "int move_mount(int " from_dirfd ", const char *" from_pathname ","
> +.BI " int " to_dirfd ", const char *" to_pathname ","
> +.BI " unsigned int " flags );
> +.fi
> +.PP
> +.IR Note :
> +There is no glibc wrapper for this system call.
> +.SH DESCRIPTION
> +The
> +.BR move_mount ()
> +call moves a mount from one place to another; it can also be used to attach
> an
> +unattached mount created by
s/created/previously created/ ?
> +.BR fsmount "() or " open_tree "() with " OPEN_TREE_CLONE .
> +.PP
> +If
> +.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 again
> and
> +again and again, detaching it from the previous mountpoint each time.
s/again and again and again/repeatedly/
s/mountpoint/mount point/
> +.PP
> +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 .
> +.PP
> +The caller does, however, require the appropriate capabilities or permission
> +to effect a mount.
Maybe better: s/effect/create/
> +.PP
> +.BR move_mount ()
> +uses
> +.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:
> +.TP
> +[*] 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.
> +.TP
> +[*] By cwd-relative path.
> +The pathname points to a relative path and the dirfd is
> +.IR AT_FDCWD .
> +The file is looked up by name, starting from the current working directory.
> +.TP
> +[*] 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 .
> +.TP
> +[*] By file descriptor.
> +The pathname points to "", the dirfd points directly to the mount object to
Better: The pathname is an empty string ("")
> +move or the destination mount point and the appropriate
> +.B *_EMPTY_PATH
> +flag is set.
> +.PP
> +.I flags
> +can be used to influence a path-based lookup. A value for
s/A value/The value/
> +.I flags
> +is constructed by OR'ing together zero or more of the following constants:
> +.TP
> +.BR
[PATCH 2/5] Add manpages for move_mount(2) and open_tree(2)
Add manual pages to document the move_mount and open_tree() system calls.
Signed-off-by: David Howells
---
man2/move_mount.2 | 275 +
1 file changed, 275 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 0..aae9013fa
--- /dev/null
+++ b/man2/move_mount.2
@@ -0,0 +1,275 @@
+'\" t
+.\" Copyright (c) 2020 David Howells
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" 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.
+.\" %%%LICENSE_END
+.\"
+.TH MOVE_MOUNT 2 2020-08-07 "Linux" "Linux Programmer's Manual"
+.SH NAME
+move_mount \- Move mount objects around the filesystem topology
+.SH SYNOPSIS
+.nf
+.B #include
+.br
+.B #include
+.br
+.B #include
+.br
+.BR "#include" "/* Definition of AT_* constants */"
+.PP
+.BI "int move_mount(int " from_dirfd ", const char *" from_pathname ","
+.BI " int " to_dirfd ", const char *" to_pathname ","
+.BI " unsigned int " flags );
+.fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call.
+.SH DESCRIPTION
+The
+.BR move_mount ()
+call moves a mount from one place to another; it can also be used to attach an
+unattached mount created by
+.BR fsmount "() or " open_tree "() with " OPEN_TREE_CLONE .
+.PP
+If
+.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 again and
+again and again, detaching it from the previous mountpoint each time.
+.PP
+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 .
+.PP
+The caller does, however, require the appropriate capabilities or permission
+to effect a mount.
+.PP
+.BR move_mount ()
+uses
+.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:
+.TP
+[*] 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.
+.TP
+[*] By cwd-relative path.
+The pathname points to a relative path and the dirfd is
+.IR AT_FDCWD .
+The file is looked up by name, starting from the current working directory.
+.TP
+[*] 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 .
+.TP
+[*] By file descriptor.
+The pathname points to "", the dirfd points directly to the mount object to
+move or the destination mount point and the appropriate
+.B *_EMPTY_PATH
+flag is set.
+.PP
+.I flags
+can be used to influence a path-based lookup. A value for
+.I flags
+is constructed by OR'ing together zero or more of the following constants:
+.TP
+.BR MOVE_MOUNT_F_EMPTY_PATH
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+If
+.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)
+.B O_PATH
+flag or
+.BR open_tree ())
+If
+.I from_dirfd
+is
+.BR AT_FDCWD ,
+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
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.TP
+.B MOVE_MOUNT_T_EMPTY_PATH
+As above, but operating on
+.IR to_pathname " and " to_dirfd .
+.TP
+.B MOVE_MOUNT_F_NO_AUTOMOUNT
+Don't automount the terminal ("basename")
