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")