Re: [PATCH 21/23] mount_setattr.2: Minor tweaks to Chirstian's patch

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Alex,

All of the below looks good, with one small detail noted below.
I've applied this patch (after fixing the typo in the subject line).

On 8/8/21 10:41 AM, Alejandro Colomar wrote:
> - Fix SYNOPSIS to fit in 78 columns
> 
>   Also, we don't show when an include is included for a specific type,
>   unless that header is included _only_ for the type,
>   or there might be confusion (e.g., termios).
>   Instead, that type should be documented in system_data_types(7),
>   with a link page mount_attr-struct(3).
> 
> - Fix references to mount_setattr().  See man-pages(7):
> 
>        Any reference to the subject of the current manual page should be writ‐
>        ten with the name in bold followed by a pair of  parentheses  in  Roman
>        (normal)  font.   For  example, in the fcntl(2) man page, references to
>        the subject of the page would be written as:  fcntl().   The  preferred
>        way to write this in the source file is:
> 
>            .BR fcntl ()
> 
> - Fix line breaks according to semantic newline rules (and add some commas)
> - Fix wrong usage of .IR when .RI should have been used
> - Fix formatting of variable part in FOO<number>:
>   - Make italic the variable part (as groff_man(7) recommends)
>   - Remove <>
>   - Use syntax recommended by G. Branden Robinson (groff)
> 
> - Fix unnecessary uses of .BR or .IR when .B or .I would suffice
> - Fix formatting of punctuation
> 
>   In some cases, it was in italics or bold, and it should always be in roman.
> 
> - Use uppercase to begin text, even in bullet points, since those were
>   multi-sentence.
> 
> - Simplify usage of .RS/.RE in combination with .IP
> - s/fat/FAT/ as fs(7) does
> - Slightly reword some sentences for consistency
> - Use Linux-specific for consistency with other pages (in VERSIONS)
> - EXAMPLES: Place the return type in a line of its own (as in other pages)
> - Fix alignment of code
> - Replace unnecessary use of the GNU extension ({}) by do {} while (0)
> 
>   In that case, there was no return value (moreover, it's a noreturn).
> 
> - Break complex declaration lines into a line for each variable
> 
>   The variables were being initialized, some to non-zero values,
>   so for clarity, a line for each one seems more appropriate.
> 
> - Add const to pointers when possible

One of those changes resulted in compiler warnings with cc -Wall;
I reverted that change.

> - s/\\/\e/
> - Remove unmatched groff commands
> 
> Cc: Christian Brauner <brauner@kernel.org>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Cheers,

Michael

> ---
>  man2/mount_setattr.2 | 446 ++++++++++++++++++++++---------------------
>  1 file changed, 225 insertions(+), 221 deletions(-)
> 
> diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2
> index 16881d90d..70ab4592e 100644
> --- a/man2/mount_setattr.2
> +++ b/man2/mount_setattr.2
> @@ -30,13 +30,13 @@ mount_setattr \- change mount properties of a mount or mount tree
>  
>  .PP
>  .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
> -.BR "#include <linux/mount.h>" " /* Definition of struct mount_attr and MOUNT_ATTR_* constants */"
> +.BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
>  .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
>  .B #include <unistd.h>
>  .PP
> -.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path \
> -", unsigned int " flags \
> -", struct mount_attr *" attr ", size_t " size );
> +.BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path ,
> +.BI "            unsigned int " flags ", struct mount_attr *" attr \
> +", size_t " size );
>  .fi
>  .PP
>  .IR Note :
> @@ -46,13 +46,13 @@ necessitating the use of
>  .BR syscall (2).
>  .SH DESCRIPTION
>  The
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  system call changes the mount properties of a mount or entire mount tree.
>  If
>  .I path
>  is a relative pathname,
> -then it is interpreted relative to the directory referred to by the file
> -descriptor
> +then it is interpreted relative to
> +the directory referred to by the file descriptor
>  .IR dfd .
>  If
>  .I dfd
> @@ -60,24 +60,25 @@ is the special value
>  .B AT_FDCWD
>  then
>  .I path
> -is taken to be relative to the current working directory of the calling process.
> +is interpreted relative to
> +the current working directory of the calling process.
>  If
>  .I path
>  is the empty string and
> -.BR AT_EMPTY_PATH
> +.B AT_EMPTY_PATH
>  is specified in
> -.I flags
> +.IR flags ,
>  then the mount properties of the mount identified by
>  .I dfd
>  are changed.
>  .PP
>  The
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  system call uses an extensible structure
> -.IR ( "struct mount_attr" )
> +.RI ( "struct mount_attr" )
>  to allow for future extensions.
>  Any non-flag extensions to
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  will be implemented as new fields appended to the above structure,
>  with a zero value in a new field resulting in the kernel behaving
>  as though that extension field was not present.
> @@ -94,17 +95,18 @@ The
>  argument should usually be specified as
>  .IR "sizeof(struct mount_attr)" .
>  However,
> -if the caller does not intend to make use of features that got
> -introduced after the initial version of
> +if the caller does not intend to make use of features that
> +got introduced after the initial version of
>  .I struct mount_attr
> -they are free to pass the size of the initial struct together with the larger
> -struct.
> -This allows the kernel to not copy later parts of the struct that aren't used
> -anyway.
> +they are free to pass
> +the size of the initial struct together with the larger struct.
> +This allows the kernel to not copy later parts of the struct
> +that aren't used anyway.
>  With each extension that changes the size of
>  .I struct mount_attr
>  the kernel will expose a define of the form
> -.BR MOUNT_ATTR_SIZE_VER<number> .
> +.BI MOUNT_ATTR_SIZE_VER number\c
> +\&.
>  For example the macro for the size of the initial version of
>  .I struct mount_attr
>  is
> @@ -118,7 +120,8 @@ The supported values are:
>  .B AT_EMPTY_PATH
>  If
>  .I path
> -is the empty string change the mount properties on
> +is the empty string,
> +change the mount properties on
>  .I dfd
>  itself.
>  .TP
> @@ -134,7 +137,7 @@ Don't trigger automounts.
>  The
>  .I attr
>  argument of
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  is a structure of the following form:
>  .PP
>  .in +4n
> @@ -152,18 +155,21 @@ The
>  .I attr_set
>  and
>  .I attr_clr
> -members are used to specify the mount properties that are supposed to be set or
> -cleared for a mount or mount tree.
> +members are used to specify the mount properties that
> +are supposed to be set or cleared for a mount or mount tree.
>  Flags set in
>  .I attr_set
> -enable a property on a mount or mount tree and flags set in
> +enable a property on a mount or mount tree,
> +and flags set in
>  .I attr_clr
>  remove a property from a mount or mount tree.
>  .PP
> -When changing mount properties the kernel will first clear the flags specified
> +When changing mount properties,
> +the kernel will first clear the flags specified
>  in the
>  .I attr_clr
> -field and then set the flags specified in the
> +field,
> +and then set the flags specified in the
>  .I attr_set
>  field:
>  .PP
> @@ -192,8 +198,8 @@ mnt->mnt_flags = current_mnt_flags;
>  .in
>  .PP
>  The effect of this change will be a mount or mount tree that is read-only,
> -blocks the execution of set-user-ID and set-group-ID binaries but does allow to
> -execute programs and access to devices nodes.
> +blocks the execution of set-user-ID and set-group-ID binaries,
> +but does allow to execute programs and access to devices nodes.
>  Multiple changes with the same set of flags requested
>  in
>  .I attr_clr
> @@ -210,7 +216,8 @@ fields:
>  .B MOUNT_ATTR_RDONLY
>  If set in
>  .I attr_set
> -makes the mount read-only and if set in
> +makes the mount read-only,
> +and if set in
>  .I attr_clr
>  removes the read-only setting if set on the mount.
>  .TP
> @@ -227,46 +234,50 @@ and file capability restriction if set on this mount.
>  .B MOUNT_ATTR_NODEV
>  If set in
>  .I attr_set
> -prevents access to devices on this mount and if set in
> +prevents access to devices on this mount,
> +and if set in
>  .I attr_clr
> -removes the device access restriction if set on this mount.
> +removes the restriction that prevented accesing devices on this mount.
>  .TP
> -.BR MOUNT_ATTR_NOEXEC
> +.B MOUNT_ATTR_NOEXEC
>  If set in
>  .I attr_set
> -prevents executing programs on this mount and if set in
> +prevents executing programs on this mount,
> +and if set in
>  .I attr_clr
> -removes the restriction to execute programs on this mount.
> +removes the restriction that prevented executing programs on this mount.
>  .TP
> -.BR MOUNT_ATTR_NOSYMFOLLOW
> +.B MOUNT_ATTR_NOSYMFOLLOW
>  If set in
>  .I attr_set
> -prevents following symlinks on this mount and if set in
> +prevents following symlinks on this mount,
> +and if set in
>  .I attr_clr
> -removes the restriction to not follow symlinks on this mount.
> +removes the restriction that prevented following symlinks on this mount.
>  .TP
>  .B MOUNT_ATTR_NODIRATIME
>  If set in
>  .I attr_set
> -prevents updating access time for directories on this mount and if set in
> +prevents updating access time for directories on this mount,
> +and if set in
>  .I attr_clr
> -removes access time restriction for directories.
> +removes the restriction that prevented updating access time for directories.
>  Note that
> -.BR MOUNT_ATTR_NODIRATIME
> -can be combined with other access time settings and is implied
> -by the noatime setting.
> +.B MOUNT_ATTR_NODIRATIME
> +can be combined with other access time settings
> +and is implied by the noatime setting.
>  All other access time settings are mutually exclusive.
>  .TP
>  .BR MOUNT_ATTR__ATIME " - Changing access time settings
> -In the new mount api the access time values are an enum starting from 0.
> +In the new mount API the access time values are an enum starting from 0.
>  Even though they are an enum in contrast to the other mount flags such as
> -.BR MOUNT_ATTR_NOEXEC
> +.BR MOUNT_ATTR_NOEXEC ,
>  they are nonetheless passed in
>  .I attr_set
>  and
>  .I attr_clr
>  for consistency with
> -.BR fsmount (2)
> +.BR fsmount (2),
>  which introduced this behavior.
>  .IP
>  Note,
> @@ -281,68 +292,67 @@ in the
>  .I attr_clr
>  field.
>  The kernel will verify that
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  isn't partially set in
> -.I attr_clr
> +.IR attr_clr ,
>  and that
>  .I attr_set
>  doesn't have any access time bits set if
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  isn't set in
>  .IR attr_clr .
>  .RS
>  .TP
>  .B MOUNT_ATTR_RELATIME
>  When a file is accessed via this mount,
> -update the file's last access time
> -(atime)
> -only if the current value of atime is less than or equal to the file's
> -last modification time (mtime) or last status change time (ctime).
> +update the file's last access time (atime)
> +only if the current value of atime is less than or equal to
> +the file's last modification time (mtime) or last status change time (ctime).
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_RELATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_RELATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .TP
> -.BR MOUNT_ATTR_NOATIME
> +.B MOUNT_ATTR_NOATIME
>  Do not update access times for (all types of) files on this mount.
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_NOATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_NOATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .TP
> -.BR MOUNT_ATTR_STRICTATIME
> -Always update the last access time (atime) when files are accessed on this
> -mount.
> +.B MOUNT_ATTR_STRICTATIME
> +Always update the last access time (atime)
> +when files are accessed on this mount.
>  .IP
> -To enable this access time setting on a mount or mount tree
> -.BR MOUNT_ATTR_STRICTATIME
> +To enable this access time setting on a mount or mount tree,
> +.B MOUNT_ATTR_STRICTATIME
>  must be set in
>  .I attr_set
>  and
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  must be set in the
>  .I attr_clr
>  field.
>  .RE
>  .TP
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  If set in
>  .I attr_set
>  creates an idmapped mount.
> -Since it is not supported to change the idmapping of a mount after it has been
> -idmapped,
> +Since it is not supported to
> +change the idmapping of a mount after it has been idmapped,
>  it is invalid to specify
>  .B MOUNT_ATTR_IDMAP
>  in
> @@ -350,54 +360,51 @@ in
>  The idmapping is taken from the user namespace specified in
>  .I userns_fd
>  and attached to the mount.
> -More details can be found in subsequent paragraphs.
>  .IP
> -Creating an idmapped mount allows to change the ownership of all files located
> -under a mount.
> -Thus, idmapped mounts make it possible to change ownership in a temporary and
> -localized way.
> -It is a localized change because ownership changes are restricted to a specific
> -mount.
> +Creating an idmapped mount allows to
> +change the ownership of all files located under a mount.
> +Thus, idmapped mounts make it possible to
> +change ownership in a temporary and localized way.
> +It is a localized change because
> +ownership changes are restricted to a specific mount.
>  All other users and locations where the filesystem is exposed are unaffected.
> -And it is a temporary change because ownership changes are tied to the lifetime
> -of the mount.
> +And it is a temporary change because
> +ownership changes are tied to the lifetime of the mount.
>  .IP
> -Whenever callers interact with the filesystem through an idmapped mount the
> -idmapping of the mount will be applied to user and group IDs associated with
> -filesystem objects.
> -This encompasses the user and group IDs associated with inodes and also
> -the following
> +Whenever callers interact with the filesystem through an idmapped mount,
> +the idmapping of the mount will be applied to
> +user and group IDs associated with filesystem objects.
> +This encompasses the user and group IDs associated with inodes
> +and also the following
>  .BR xattr (7)
>  keys:
>  .RS
> -.RS
> -.IP \(bu 2
> -.IR security.capability
> +.IP \(bu
> +.IR security.capability ,
>  whenever filesystem
>  .BR capabilities (7)
>  are stored or returned in the
>  .I VFS_CAP_REVISION_3
> -format which stores a rootid alongside the capabilities.
> -.IP \(bu 2
> +format,
> +which stores a rootid alongside the capabilities.
> +.IP \(bu
>  .I system.posix_acl_access
>  and
> -.I system.posix_acl_default
> +.IR system.posix_acl_default ,
>  whenever user IDs or group IDs are stored in
> -.BR ACL_USER
> -and
> -.BR ACL_GROUP
> +.B ACL_USER
> +or
> +.B ACL_GROUP
>  entries.
>  .RE
> -.RE
>  .IP
>  The following conditions must be met in order to create an idmapped mount:
>  .RS
> -.RS
> -.IP \(bu 2
> +.IP \(bu
>  The caller must have
>  .I CAP_SYS_ADMIN
>  in the initial user namespace.
> -.IP \(bu 2
> +.IP \(bu
>  The filesystem must be mounted in the initial user namespace.
>  .IP \(bu
>  The underlying filesystem must support idmapped mounts.
> @@ -405,9 +412,9 @@ Currently
>  .BR xfs (5),
>  .BR ext4 (5)
>  and
> -.BR fat
> -filesystems support idmapped mounts with more filesystems being actively worked
> -on.
> +.B FAT
> +filesystems support idmapped mounts
> +with more filesystems being actively worked on.
>  .IP \(bu
>  The mount must not already be idmapped.
>  This also implies that the idmapping of a mount cannot be altered.
> @@ -420,24 +427,24 @@ with the
>  .I OPEN_TREE_CLONE
>  flag and it must not already have been visible in the filesystem.
>  .RE
> -.RE
>  .IP
>  Idmappings can be created for user IDs, group IDs, and project IDs.
>  An idmapping is essentially a mapping of a range of user or group IDs into
>  another or the same range of user or group IDs.
> -Idmappings are usually written as three numbers either separated by white space
> -or a full stop.
> -The first two numbers specify the starting user or group ID in each of the two
> -user namespaces.
> +Idmappings are usually written as three numbers
> +either separated by white space or a full stop.
> +The first two numbers specify the starting user or group ID
> +in each of the two user namespaces.
>  The third number specifies the range of the idmapping.
>  For example, a mapping for user IDs such as 1000:1001:1 would indicate that
> -user ID 1000 in the caller's user namespace is mapped to user ID 1001 in its
> -ancestor user namespace.
> -Since the map range is 1 only user ID 1000 is mapped.
> +user ID 1000 in the caller's user namespace is mapped to
> +user ID 1001 in its ancestor user namespace.
> +Since the map range is 1,
> +only user ID 1000 is mapped.
>  It is possible to specify up to 340 idmappings for each idmapping type.
> -If any user IDs or group IDs are not mapped all files owned by that unmapped
> -user or group ID will appear as being owned by the overflow user ID or overflow
> -group ID respectively.
> +If any user IDs or group IDs are not mapped,
> +all files owned by that unmapped user or group ID will appear as
> +being owned by the overflow user ID or overflow group ID respectively.
>  Further details and instructions for setting up idmappings can be found in the
>  .BR user_namespaces (7)
>  man page.
> @@ -445,69 +452,70 @@ man page.
>  In the common case the user namespace passed in
>  .I userns_fd
>  together with
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  in
>  .I attr_set
>  to create an idmapped mount will be the user namespace of a container.
> -In other scenarios it will be a dedicated user namespace associated with a
> -user's login session as is the case for portable home directories in
> +In other scenarios it will be a dedicated user namespace associated with
> +a user's login session as is the case for portable home directories in
>  .BR systemd-homed.service (8) ).
> -It is also perfectly fine to create a dedicated user namespace for the sake of
> -idmapping a mount.
> +It is also perfectly fine to create a dedicated user namespace
> +for the sake of idmapping a mount.
>  .IP
> -Idmapped mounts can be useful in the following and a variety of other
> -scenarios:
> +Idmapped mounts can be useful in the following
> +and a variety of other scenarios:
>  .RS
> -.RS
> -.IP \(bu 2
> -sharing files between multiple users or multiple machines especially in
> -complex scenarios.
> +.IP \(bu
> +Sharing files between multiple users or multiple machines,
> +especially in complex scenarios.
>  For example,
>  idmapped mounts are used to implement portable home directories in
>  .BR systemd-homed.service (8)
> -where they allow users to move their home directory to an external storage
> -device and use it on multiple computers where they are assigned different user IDs
> -and group IDs.
> -This effectively makes it possible to assign random user IDs and group IDs at login time.
> +where they allow users to move their home directory
> +to an external storage device
> +and use it on multiple computers
> +where they are assigned different user IDs and group IDs.
> +This effectively makes it possible to
> +assign random user IDs and group IDs at login time.
>  .IP \(bu
> -sharing files from the host with unprivileged containers.
> -This allows user to avoid having to change ownership permanently through
> +Sharing files from the host with unprivileged containers.
> +This allows a user to avoid having to change ownership permanently through
>  .BR chown (2) .
>  .IP \(bu
> -idmapping a container's root filesystem.
> -Users don't need to change ownership
> -permanently through
> +Idmapping a container's root filesystem.
> +Users don't need to change ownership permanently through
>  .BR chown (2) .
> -Especially for large root filesystems using
> +Especially for large root filesystems, using
>  .BR chown (2)
>  can be prohibitively expensive.
>  .IP \(bu
> -sharing files between containers with non-overlapping
> -idmappings.
> +Sharing files between containers with non-overlapping idmappings.
>  .IP \(bu
> -implementing discretionary access (DAC) permission checking for fileystems
> -lacking a concept of ownership.
> +Implementing discretionary access (DAC) permission checking
> +for fileystems lacking a concept of ownership.
>  .IP \(bu
> -efficiently change ownership on a per-mount basis.
> +Efficiently change ownership on a per-mount basis.
>  In contrast to
> -.BR chown (2)
> +.BR chown (2),
>  changing ownership of large sets of files is instantenous with idmapped mounts.
> -This is especially useful when ownership of an entire root filesystem of a
> -virtual machine or container is to be changed as we've mentioned above.
> -With idmapped mounts a single
> -.BR mount_setattr (2)
> +This is especially useful when ownership of
> +an entire root filesystem of a virtual machine or container
> +is to be changed as we've mentioned above.
> +With idmapped mounts,
> +a single
> +.BR mount_setattr ()
>  system call will be sufficient to change the ownership of all files.
>  .IP \(bu
> -taking the current ownership into account.
> -Idmappings specify precisely what a user or group ID is supposed to be
> -mapped to.
> +Taking the current ownership into account.
> +Idmappings specify precisely
> +what a user or group ID is supposed to be mapped to.
>  This contrasts with the
>  .BR chown (2)
> -system call which cannot by itself take the current ownership of the files it
> -changes into account.
> +system call which cannot by itself
> +take the current ownership of the files it changes into account.
>  It simply changes the ownership to the specified user ID and group ID.
>  .IP \(bu
> -locally and temporarily restricted ownership changes.
> +Locally and temporarily restricted ownership changes.
>  Idmapped mounts allow to change ownership locally,
>  restricting it to specific mounts,
>  and temporarily as the ownership changes only apply as long as the mount exists.
> @@ -516,7 +524,6 @@ changing ownership via the
>  .BR chown (2)
>  system call changes the ownership globally and permanently.
>  .RE
> -.RE
>  .PP
>  The
>  .I propagation
> @@ -538,13 +545,13 @@ will propagate to the other mount points that are members of the peer group.
>  Propagation here means that the same mount or unmount will automatically occur
>  under all of the other mount points in the peer group.
>  Conversely,
> -mount and unmount events that take place under peer mount points will propagate
> -to this mount point.
> +mount and unmount events that take place under peer mount points
> +will propagate to this mount point.
>  .TP
>  .B MS_SLAVE
>  Turn all mounts into dependent mounts.
> -Mount and unmount events propagate into this mount point from a shared peer
> -group.
> +Mount and unmount events propagate into this mount point
> +from a shared peer group.
>  Mount and unmount events under this mount point do not propagate to any peer.
>  .TP
>  .B MS_UNBINDABLE
> @@ -558,7 +565,7 @@ when replicating that subtree to produce the target subtree.
>  .PP
>  .SH RETURN VALUE
>  On success,
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  returns zero.
>  On error,
>  \-1 is returned and
> @@ -576,8 +583,8 @@ is not a valid file descriptor.
>  .TP
>  .B EBUSY
>  The caller tried to change the mount to
> -.BR MOUNT_ATTR_RDONLY
> -but the mount still has files open for writing.
> +.B MOUNT_ATTR_RDONLY
> +but the mount still holds files open for writing.
>  .TP
>  .B EINVAL
>  The path specified via the
> @@ -585,7 +592,7 @@ The path specified via the
>  and
>  .I path
>  arguments to
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  isn't a mountpoint.
>  .TP
>  .B EINVAL
> @@ -612,11 +619,11 @@ field of
>  .TP
>  .B EINVAL
>  More than one of
> -.BR MS_SHARED,
> -.BR MS_SLAVE,
> -.BR MS_PRIVATE,
> +.BR MS_SHARED ,
> +.BR MS_SLAVE ,
> +.BR MS_PRIVATE ,
>  or
> -.BR MS_UNBINDABLE
> +.B MS_UNBINDABLE
>  was set in
>  .I propagation
>  field of
> @@ -626,13 +633,13 @@ field of
>  An access time setting was specified in the
>  .I attr_set
>  field without
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  being set in the
>  .I attr_clr
>  field.
>  .TP
>  .B EINVAL
> -.BR MOUNT_ATTR_IDMAP
> +.B MOUNT_ATTR_IDMAP
>  was specified in
>  .IR attr_clr .
>  .TP
> @@ -645,8 +652,8 @@ which exceeds
>  .B EINVAL
>  A valid file descriptor value was specified in
>  .I userns_fd
> -but the file descriptor wasn't a namespace file descriptor or did not refer to
> -a user namespace.
> +but the file descriptor wasn't a namespace file descriptor
> +or did not refer to a user namespace.
>  .TP
>  .B EINVAL
>  The underlying filesystem does not support idmapped mounts.
> @@ -660,7 +667,7 @@ the mount is already visible in the filesystem.
>  A partial access time setting was specified in
>  .I attr_clr
>  instead of
> -.BR MOUNT_ATTR__ATIME
> +.B MOUNT_ATTR__ATIME
>  being set.
>  .TP
>  .B EINVAL
> @@ -674,14 +681,14 @@ A pathname was empty or had a nonexistent component.
>  .TP
>  .B ENOMEM
>  When changing mount propagation to
> -.BR MS_SHARED
> +.B 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.
>  .TP
>  .B ENOSPC
>  When changing mount propagation to
> -.BR MS_SHARED
> +.B 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.
> @@ -690,25 +697,25 @@ id allocation implementation used.
>  .TP
>  .B EPERM
>  One of the mounts had at least one of
> -.BR MOUNT_ATTR_NOATIME,
> -.BR MOUNT_ATTR_NODEV,
> -.BR MOUNT_ATTR_NODIRATIME,
> -.BR MOUNT_ATTR_NOEXEC,
> -.BR MOUNT_ATTR_NOSUID,
> +.BR MOUNT_ATTR_NOATIME ,
> +.BR MOUNT_ATTR_NODEV ,
> +.BR MOUNT_ATTR_NODIRATIME ,
> +.BR MOUNT_ATTR_NOEXEC ,
> +.BR MOUNT_ATTR_NOSUID ,
>  or
> -.BR MOUNT_ATTR_RDONLY
> +.B MOUNT_ATTR_RDONLY
>  set and the flag is locked.
>  Mount attributes become locked on a mount if:
>  .RS
> -.IP \(bu 2
> -a new mount or mount tree is created causing mount propagation across user
> +.IP \(bu
> +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
>  properties from being altered.
>  .IP \(bu
> -a new mount and user namespace pair is created.
> +A new mount and user namespace pair is created.
>  This happens for example when specifying
> -.BR CLONE_NEWUSER | CLONE_NEWNS
> +.B CLONE_NEWUSER | CLONE_NEWNS
>  in
>  .BR unshare (2),
>  .BR clone (2),
> @@ -731,18 +738,18 @@ The caller does not have
>  .I CAP_SYS_ADMIN
>  in the initial user namespace.
>  .SH VERSIONS
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  first appeared in Linux 5.12.
>  .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
>  .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
>  .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
>  .SH CONFORMING TO
> -.BR mount_setattr (2)
> -is Linux specific.
> +.BR mount_setattr ()
> +is Linux-specific.
>  .SH NOTES
>  .SS Extensibility
>  In order to allow for future extensibility,
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  along with other system calls such as
>  .BR openat2 (2)
>  and
> @@ -751,7 +758,7 @@ requires the user-space application to specify the size of the
>  .I mount_attr
>  structure that it is passing.
>  By providing this information, it is possible for
> -.BR mount_setattr (2)
> +.BR mount_setattr ()
>  to provide both forwards- and backwards-compatibility, with
>  .I size
>  acting as an implicit version number.
> @@ -771,10 +778,9 @@ and let
>  .I ksize
>  be the size of the structure which the kernel supports,
>  then there are three cases to consider:
> -.RS
> -.IP \(bu 2
> +.IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  equals
>  .IR usize ,
>  then there is no version mismatch and
> @@ -782,31 +788,32 @@ then there is no version mismatch and
>  can be used verbatim.
>  .IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  is larger than
>  .IR usize ,
> -then there are some extension fields that the kernel supports which the
> -user-space application is unaware of.
> +then there are some extension fields that the kernel supports
> +which the user-space application is unaware of.
>  Because a zero value in any added extension field signifies a no-op,
> -the kernel treats all of the extension fields not provided by the user-space
> -application as having zero values.
> +the kernel treats all of the extension fields
> +not provided by the user-space application
> +as having zero values.
>  This provides backwards-compatibility.
>  .IP \(bu
>  If
> -.IR ksize
> +.I ksize
>  is smaller than
>  .IR usize ,
>  then there are some extension fields which the user-space application is aware
>  of but which the kernel does not support.
>  Because any extension field must have its zero values signify a no-op,
> -the kernel can safely ignore the unsupported extension fields if they are
> -all zero.
> -If any unsupported extension fields are non-zero, then \-1 is returned and
> +the kernel can safely ignore the unsupported extension fields
> +if they are all zero.
> +If any unsupported extension fields are non-zero,
> +then \-1 is returned and
>  .I errno
>  is set to
>  .BR E2BIG .
>  This provides forwards-compatibility.
> -.RE
>  .PP
>  Because the definition of
>  .I struct mount_attr
> @@ -842,7 +849,7 @@ attr.attr_clr = MOUNT_ATTR_NODEV;
>  .PP
>  A user-space application that wishes to determine which extensions the running
>  kernel supports can do so by conducting a binary search on
> -.IR size
> +.I size
>  with a structure which has every byte nonzero
>  (to find the largest value which doesn't produce an error of
>  .BR E2BIG ) .
> @@ -865,30 +872,26 @@ with a structure which has every byte nonzero
>  #include <sys/syscall.h>
>  #include <unistd.h>
>  
> -static inline int mount_setattr(int dfd,
> -                                const char *path,
> -                                unsigned int flags,
> -                                struct mount_attr *attr,
> -                                size_t size)
> +static inline int
> +mount_setattr(int dfd, const char *path, unsigned int flags,
> +              struct mount_attr *attr, size_t size)
>  {
> -    return syscall(SYS_mount_setattr, dfd, path,
> -                   flags, attr, size);
> +    return syscall(SYS_mount_setattr, dfd, path, flags, attr, size);
>  }
>  
> -static inline int open_tree(int dfd, const char *filename,
> +static inline int
> +open_tree(int dfd, const char *filename,
>                              unsigned int flags)
>  {
>      return syscall(SYS_open_tree, dfd, filename, flags);
>  }
>  
> -static inline int move_mount(int from_dfd,
> -                             const char *from_pathname,
> -                             int to_dfd,
> -                             const char *to_pathname,
> -                             unsigned int flags)
> +static inline int
> +move_mount(int from_dfd, const char *from_pathname,
> +           int to_dfd, const char *to_pathname, unsigned int flags)
>  {
> -    return syscall(SYS_move_mount, from_dfd,
> -                   from_pathname, to_dfd, to_pathname, flags);
> +    return syscall(SYS_move_mount, from_dfd, from_pathname,
> +                   to_dfd, to_pathname, flags);
>  }
>  
>  static const struct option longopts[] = {
> @@ -902,23 +905,25 @@ static const struct option longopts[] = {
>      { NULL,             0,                  NULL,   0 },
>  };
>  
> -#define exit_log(format, ...)                   \\
> -    ({                                          \\
> -        fprintf(stderr, format, ##__VA_ARGS__); \\
> -        exit(EXIT_FAILURE);                     \\
> -    })
> +#define exit_log(format, ...)  do           \e
> +{                                           \e
> +    fprintf(stderr, format, ##__VA_ARGS__); \e
> +    exit(EXIT_FAILURE);                     \e
> +} while (0)
>  
> -int main(int argc, char *argv[])
> +int
> +main(int argc, char *argv[])
>  {
> -    int fd_userns = \-EBADF, index = 0;
> +    int fd_userns = \-EBADF;
> +    int index = 0;
>      bool recursive = false;
>      struct mount_attr *attr = &(struct mount_attr){};
>      const char *source, *target;
>      int fd_tree, new_argc, ret;
> -    char *const *new_argv;
> +    const char *const *new_argv;
>  
>      while ((ret = getopt_long_only(argc, argv, "",
> -                                  longopts, &index)) != \-1) {
> +                                   longopts, &index)) != \-1) {
>          switch (ret) {
>          case 'a':
>              fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
> @@ -985,7 +990,6 @@ int main(int argc, char *argv[])
>      exit(EXIT_SUCCESS);
>  }
>  .EE
> -.fi
>  .SH SEE ALSO
>  .BR capabilities (7),
>  .BR clone (2),
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/