mount_setattr.2: Further tweaks after feedback from Christian Brauner

Reported-by: Christian Brauner <christian.brauner@ubuntu.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/access.2

@@ -278,8 +278,12 @@ The following additional errors can occur for
 .BR faccessat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 Invalid flag specified in

man2/chmod.2

@@ -309,8 +309,12 @@ The following additional errors can occur for
 .BR fchmodat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 Invalid flag specified in

man2/chown.2

@@ -293,8 +293,12 @@ The following additional errors can occur for
 .BR fchownat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 Invalid flag specified in

man2/execveat.2

@@ -121,9 +121,12 @@ can also occur for
 The following additional errors can occur for
 .BR execveat ():
 .TP
-.B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 Invalid flag specified in

man2/fanotify_mark.2

@@ -357,7 +357,62 @@ has the value
 .BR AT_FDCWD ,
 then the filesystem object to be marked is determined by interpreting
 .I pathname
-relative the current working directory.
+relative to the current working directory.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
+.PP
+The
+.BR mount_setattr ()
+system call uses an extensible structure
+.RI ( "struct mount_attr" )
+to allow for future extensions.
+Any non-flag extensions to
+.BR mount_setattr ()
+will be implemented as new fields appended to the this structure,
+with a zero value in a new field resulting in the kernel behaving
+as though that extension field was not present.
+Therefore,
+the caller
+.I must
+zero-fill this structure on initialization.
+See the "Extensibility" subsection under
+.B NOTES
+for more details.
+.PP
+The
+.I size
+argument should usually be specified as
+.IR "sizeof(struct mount_attr)" .
+However, if the caller is using a kernel that supports an extended
+.IR "struct mount_attr" ,
+but the caller does not intend to make use of these features,
+it is possible to pass the size of an earlier
+version of the structure together with the extended structure.
+This allows the kernel to not copy later parts of the structure
+that aren't used anyway.
+With each extension that changes the size of
+.IR "struct mount_attr" ,
+the kernel will expose a definition of the form
+.BI MOUNT_ATTR_SIZE_VER number\c
+\&.
+For example, the macro for the size of the initial version of
+.I struct mount_attr
+is
+.BR MOUNT_ATTR_SIZE_VER0 .
+.PP
+The
+.I flags
+argument can be used to alter the pathname resolution behavior.
+The supported values are:
+.TP
+.B AT_EMPTY_PATH
+If
+.I pathname
+is the empty string,
+change the mount properties on
 .SH RETURN VALUE
 On success,
 .BR fanotify_mark ()
@@ -371,6 +426,14 @@ is set to indicate the error.
 An invalid file descriptor was passed in
 .IR fanotify_fd .
 .TP
+.B EBADF
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
 .B EINVAL
 An invalid value was passed in
 .IR flags

man2/futimesat.2

@@ -83,6 +83,11 @@ If
 is absolute, then
 .I dirfd
 is ignored.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
 .SH RETURN VALUE
 On success,
 .BR futimesat ()
@@ -99,8 +104,12 @@ The following additional errors can occur for
 .BR futimesat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname

man2/link.2

@@ -282,10 +282,14 @@ The following additional errors can occur for
 .BR linkat ():
 .TP
 .B EBADF
+.I oldpath
+.RI ( newpath )
+is relative but
 .I olddirfd
-or
-.I newdirfd
-is not a valid file descriptor.
+.RI ( newdirfd )
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 An invalid flag value was specified in

man2/mkdir.2

@@ -192,8 +192,12 @@ The following additional errors can occur for
 .BR mkdirat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname

man2/mknod.2

@@ -229,8 +229,12 @@ The following additional errors can occur for
 .BR mknodat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname

man2/mount_setattr.2

@@ -34,7 +34,7 @@ mount_setattr \- change properties of a mount or mount tree
 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
 .B #include <unistd.h>
 .PP
-.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" path ,
+.BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname ,
 .BI "            unsigned int " flags ", struct mount_attr *" attr \
 ", size_t " size );
 .fi
@@ -49,7 +49,7 @@ The
 .BR mount_setattr ()
 system call changes the mount properties of a mount or an entire mount tree.
 If
-.I path
+.I pathname
 is a relative pathname,
 then it is interpreted relative to
 the directory referred to by the file descriptor
@@ -59,11 +59,11 @@ If
 is the special value
 .BR AT_FDCWD ,
 then
-.I path
+.I pathname
 is interpreted relative to
 the current working directory of the calling process.
 If
-.I path
+.I pathname
 is the empty string and
 .B AT_EMPTY_PATH
 is specified in
@@ -71,6 +71,11 @@ is specified in
 then the mount properties of the mount identified by
 .I dirfd
 are changed.
+(See
+.BR openat (2)
+for an explanation of why the
+.I dirfd
+argument is useful.)
 .PP
 The
 .BR mount_setattr ()
@@ -113,12 +118,12 @@ is
 .PP
 The
 .I flags
-argument can be used to alter the path resolution behavior.
+argument can be used to alter the pathname resolution behavior.
 The supported values are:
 .TP
 .B AT_EMPTY_PATH
 If
-.I path
+.I pathname
 is the empty string,
 change the mount properties on
 .I dirfd
@@ -408,8 +413,12 @@ is set to indicate the cause of the error.
 .SH ERRORS
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EBADF
 .I userns_fd
@@ -421,10 +430,10 @@ The caller tried to change the mount to
 but the mount still holds files open for writing.
 .TP
 .B EINVAL
-The path specified via the
+The pathname specified via the
 .I dirfd
 and
-.I path
+.I pathname
 arguments to
 .BR mount_setattr ()
 isn't a mount point.
@@ -493,7 +502,7 @@ The underlying filesystem does not support ID-mapped mounts.
 .TP
 .B EINVAL
 The mount that is to be ID mapped is not a detached mount;
-that is, the mount is already visible in the filesystem.
+that is, the mount has not previously been visible in a mount namespace.
 .TP
 .B EINVAL
 A partial access-time setting was specified in
@@ -506,7 +515,8 @@ being set.
 The mount is located outside the caller's mount namespace.
 .TP
 .B EINVAL
-The underlying filesystem is mounted in a user namespace.
+The underlying filesystem has been mounted in a mount namespace that is
+owned by a noninitial user namespace
 .TP
 .B ENOENT
 A pathname was empty or had a nonexistent component.
@@ -516,16 +526,21 @@ When changing mount propagation to
 .BR MS_SHARED ,
 a new peer group ID needs to be allocated for all mounts without a peer group
 ID set.
-Allocation of this peer group ID has failed.
+This allocation failed because there was not
+enough memory to allocate the relevant internal structures.
 .TP
 .B ENOSPC
 When changing mount propagation to
 .BR MS_SHARED ,
 a new peer group ID needs to be allocated for all mounts without a peer group
 ID set.
-Allocation of this peer group ID can fail.
-Note that technically further error codes are possible that are specific to the
-ID allocation implementation used.
+This allocation failed because
+the kernel has run out of IDs.
+.\" Christian Bruner: i.e. someone has somehow managed to
+.\" allocate so many peer groups and managed to keep the kernel running
+.\" (???) that the ida has ran out of ids
+.\" Note that technically further error codes are possible that are
+.\" specific to the ID allocation implementation used.
 .TP
 .B EPERM
 One of the mounts had at least one of
@@ -541,8 +556,9 @@ Mount attributes become locked on a mount if:
 .RS
 .IP \(bu 3
 A new mount or mount tree is created causing mount propagation across user
-namespaces.
-The kernel will lock the aforementioned flags to protect these sensitive
+namespaces
+(i.e., propagation to a mount namespace owned by a different user namespace).
+The kernel will lock the aforementioned flags to prevent these sensitive
 properties from being altered.
 .IP \(bu
 A new mount and user namespace pair is created.
@@ -553,8 +569,14 @@ in
 .BR clone (2),
 or
 .BR clone3 (2).
-The aforementioned flags become locked to protect user namespaces from altering
-sensitive mount properties.
+The aforementioned flags become locked in the new mount namespace
+to prevent sensitive mount properties from being altered.
+Since the newly created mount namespace will be owned by the
+newly created user namespace,
+a calling process that is privileged in the new
+user namespace would\(emin the absence of such locking\(embe
+able to alter sensitive mount properties (e.g., to remount a mount
+that was marked read-only as read-write in the new mount namespace).
 .RE
 .TP
 .B EPERM
@@ -643,7 +665,11 @@ it must have been created by calling
 .BR open_tree (2)
 with the
 .B OPEN_TREE_CLONE
-flag and it must not already have been visible in the filesystem.
+flag and it must not already have been visible in a mount namespace.
+(To put things another way:
+the mount must not have been attached to the filesystem hierarchy
+with a system call such as
+.BR move_mount (2).)
 .PP
 ID mappings can be created for user IDs, group IDs, and project IDs.
 An ID mapping is essentially a mapping of a range of user or group IDs into
@@ -868,10 +894,10 @@ with a structure which has every byte nonzero
 #include <unistd.h>
 
 static inline int
-mount_setattr(int dirfd, const char *path, unsigned int flags,
+mount_setattr(int dirfd, const char *pathname, unsigned int flags,
               struct mount_attr *attr, size_t size)
 {
-    return syscall(SYS_mount_setattr, dirfd, path, flags, attr, size);
+    return syscall(SYS_mount_setattr, dirfd, pathname, flags, attr, size);
 }
 
 static inline int
@@ -952,7 +978,10 @@ main(int argc, char *argv[])
     const char *source = argv[optind];
     const char *target = argv[optind + 1];
 
-    int fd_tree = open_tree(\-EBADF, source,
+    /* In the following, \-1 as the \(aqdirfd\(aq argument ensures that
+       open_tree() fails if \(aqsource\(aq is not an absolute pathname. */
+
+    int fd_tree = open_tree(\-1, source,
                        OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC |
                        AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0));
     if (fd_tree == \-1)
@@ -971,7 +1000,10 @@ main(int argc, char *argv[])
 
     close(fd_userns);
 
-    ret = move_mount(fd_tree, "", \-EBADF, target,
+    /* In the following, \-1 as the \(aqto_dirfd\(aq argument ensures that
+       open_tree() fails if \(aqtarget\(aq is not an absolute pathname. */
+
+    ret = move_mount(fd_tree, "", \-1, target,
                      MOVE_MOUNT_F_EMPTY_PATH);
     if (ret == \-1)
         exit_log("%m \- Failed to attach mount to %s\en", target);

man2/open.2

@@ -926,17 +926,19 @@ system call operates in exactly the same way as
 .BR open (),
 except for the differences described here.
 .PP
+The
+.I dirfd
+argument is used in conjunction with the
+.I pathname
+argument as follows:
+.IP * 3
 If the pathname given in
 .I pathname
-is relative, then it is interpreted relative to the directory
-referred to by the file descriptor
+is absolute, then
 .I dirfd
-(rather than relative to the current working directory of
-the calling process, as is done by
-.BR open ()
-for a relative pathname).
-.PP
-If
+is ignored.
+.IP *
+If the pathname given in
 .I pathname
 is relative and
 .I dirfd
@@ -947,12 +949,36 @@ then
 is interpreted relative to the current working
 directory of the calling process (like
 .BR open ()).
-.PP
-If
+.IP *
+If the pathname given in
 .I pathname
-is absolute, then
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
 .I dirfd
-is ignored.
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR open ()
+for a relative pathname).
+In this case,
+.I dirfd
+must be a directory that was opened for reading
+.RB ( O_RDONLY )
+or using the
+.B O_PATH
+flag.
+.PP
+If the pathname given in
+.I pathname
+is relative, and
+.I dirfd
+is not a valid file descriptor, an error
+.RB ( EBADF )
+results.
+(Specifying an invalid file descriptor number in
+.I dirfd
+can be used as a means to ensure that
+.I pathname
+is absolute.)
 .\"
 .SS openat2(2)
 The
@@ -1264,8 +1290,12 @@ The following additional errors can occur for
 .BR openat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname
@@ -1611,13 +1641,14 @@ a directory file descriptor argument
 .BR futimesat (2),
 .BR linkat (2),
 .BR mkdirat (2),
-.BR move_mount (2),
 .BR mknodat (2),
+.BR move_mount (2),
 .BR name_to_handle_at (2),
 .BR open_tree (2),
 .BR openat2 (2),
 .BR readlinkat (2),
 .BR renameat (2),
+.BR renameat2 (2),
 .BR statx (2),
 .BR symlinkat (2),
 .BR unlinkat (2),

man2/open_by_handle_at.2

@@ -347,6 +347,14 @@ can fail with the following errors:
 .IR mount_fd
 is not an open file descriptor.
 .TP
+.B EBADF
+.I pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
 .B EFAULT
 .IR handle
 points outside your accessible address space.

man2/readlink.2

@@ -200,8 +200,12 @@ The following additional errors can occur for
 .BR readlinkat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname

man2/rename.2

@@ -438,9 +438,11 @@ and
 .BR renameat2 ():
 .TP
 .B EBADF
+.I oldpath
+.RI ( newpath )
+is relative but
 .I olddirfd
-or
-.I newdirfd
+.RI ( newdirfd )
 is not a valid file descriptor.
 .TP
 .B ENOTDIR

man2/stat.2

@@ -434,8 +434,12 @@ The following additional errors can occur for
 .BR fstatat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 Invalid flag specified in

man2/statx.2

@@ -142,6 +142,9 @@ is a file descriptor that refers to a directory, then
 is a relative pathname that is interpreted relative to the directory
 referred to by
 .IR dirfd .
+(See
+.BR openat (2)
+for an explanation of why this is useful.)
 .TP
 By file descriptor
 If
@@ -505,8 +508,12 @@ in the path prefix of
 .BR path_resolution (7).)
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid open file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EFAULT
 .I pathname

man2/symlink.2

@@ -131,6 +131,11 @@ If
 is absolute, then
 .I newdirfd
 is ignored.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR symlinkat ().
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
@@ -203,8 +208,12 @@ The following additional errors can occur for
 .BR symlinkat ():
 .TP
 .B EBADF
+.I linkpath
+is relative but
 .I newdirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOENT
 .I linkpath

man2/unlink.2

@@ -246,8 +246,12 @@ The following additional errors can occur for
 .BR unlinkat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B EINVAL
 An invalid flag value was specified in

man2/utimensat.2

@@ -269,7 +269,7 @@ is not a valid file descriptor.
 .B EBADF
 .RB ( utimensat ())
 .I pathname
-is a relative pathname, but
+is relative but
 .I dirfd
 is neither
 .BR AT_FDCWD

man3/mkfifo.3

@@ -111,6 +111,11 @@ If
 is absolute, then
 .I dirfd
 is ignored.
+.PP
+See
+.BR openat (2)
+for an explanation of the need for
+.BR mkfifoat ().
 .SH RETURN VALUE
 On success
 .BR mkfifo ()
@@ -162,12 +167,16 @@ The following additional errors can occur for
 .BR mkfifoat ():
 .TP
 .B EBADF
+.I pathname
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I pathname
-is a relative path and
+is a relative pathname and
 .I dirfd
 is a file descriptor referring to a file other than a directory.
 .SH VERSIONS

man3/scandir.3

@@ -204,12 +204,16 @@ The following additional errors can occur for
 .BR scandirat ():
 .TP
 .B EBADF
+.I dirp
+is relative but
 .I dirfd
-is not a valid file descriptor.
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
 .TP
 .B ENOTDIR
 .I dirp
-is a relative path and
+is a relative pathname and
 .I dirfd
 is a file descriptor referring to a file other than a directory.
 .SH VERSIONS

man7/mount_namespaces.7

@@ -149,7 +149,7 @@ attempting to unlink, rename, or remove a file or directory
 that was a mount point in another mount namespace would result in the error
 .BR EBUSY .
 That behavior had technical problems of enforcement (e.g., for NFS)
-and permitted denial-of-service attacks against more privileged users.
+and permitted denial-of-service attacks against more privileged users
 (i.e., preventing individual files from being updated
 by bind mounting on top of them).
 .\"