linux-kernel - Re: [PATCH v2 02/11] mount_setattr.2: move mount_attr struct to mount

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <cselxzuadkkf4cfx45fm3cm77mkq7gxrbzg7idr5726p52w5qa@sarhby7scgp6>
Date: Thu, 7 Aug 2025 13:11:06 +0200
From: Alejandro Colomar <alx@...nel.org>
To: Aleksa Sarai <cyphar@...har.com>
Cc: "Michael T. Kerrisk" <mtk.manpages@...il.com>, 
	Alexander Viro <viro@...iv.linux.org.uk>, Jan Kara <jack@...e.cz>, Askar Safin <safinaskar@...omail.com>, 
	"G. Branden Robinson" <g.branden.robinson@...il.com>, linux-man@...r.kernel.org, linux-api@...r.kernel.org, 
	linux-fsdevel@...r.kernel.org, linux-kernel@...r.kernel.org, 
	David Howells <dhowells@...hat.com>, Christian Brauner <brauner@...nel.org>
Subject: Re: [PATCH v2 02/11] mount_setattr.2: move mount_attr struct to
 mount_attr.2type

Hi Aleksa,

On Thu, Aug 07, 2025 at 03:44:36AM +1000, Aleksa Sarai wrote:
> As with open_how(2type), it makes sense to move this to a separate man
> page.  In addition, future man pages added in this patchset will want to
> reference mount_attr(2type).
> 
> Signed-off-by: Aleksa Sarai <cyphar@...har.com>
> ---
>  man/man2/mount_setattr.2      | 17 ++++---------
>  man/man2type/mount_attr.2type | 58 +++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 63 insertions(+), 12 deletions(-)
> 
> diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
> index c96f0657f046..d44fafc93a20 100644
> --- a/man/man2/mount_setattr.2
> +++ b/man/man2/mount_setattr.2
> @@ -114,18 +114,11 @@ .SH DESCRIPTION
>  .I attr
>  argument of
>  .BR mount_setattr ()
> -is a structure of the following form:
> -.P
> -.in +4n
> -.EX
> -struct mount_attr {
> -    __u64 attr_set;     /* Mount properties to set */
> -    __u64 attr_clr;     /* Mount properties to clear */
> -    __u64 propagation;  /* Mount propagation type */
> -    __u64 userns_fd;    /* User namespace file descriptor */
> -};
> -.EE
> -.in
> +is a pointer to a
> +.I mount_attr
> +structure,
> +described in
> +.BR mount_attr (2type).
>  .P
>  The
>  .I attr_set
> diff --git a/man/man2type/mount_attr.2type b/man/man2type/mount_attr.2type
> new file mode 100644
> index 000000000000..b7a3ace6b3b9
> --- /dev/null
> +++ b/man/man2type/mount_attr.2type
> @@ -0,0 +1,58 @@
> +

Please remove this blank.  It is not diagnosed by groff(1), but I think
it should be diagnosed (blank lines are diagnosed elsewhere).  I've
reported a bug to groff(1) (Branden will be reading this, anyway).

> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH mount_attr 2type (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +mount_attr \- what mount properties to set and clear
> +.SH LIBRARY
> +Linux kernel headers
> +.SH SYNOPSIS
> +.EX
> +.B #include <sys/mount.h>
> +.P
> +.B struct mount_attr {
> +.BR "    __u64 attr_set;" "     /* Mount properties to set */"
> +.BR "    __u64 attr_clr;" "     /* Mount properties to clear */"
> +.BR "    __u64 propagation;" "  /* Mount propagation type */"
> +.BR "    __u64 userns_fd;" "    /* User namespace file descriptor */"
> +    /* ... */
> +.B };
> +.EE
> +.SH DESCRIPTION
> +Specifies which mount properties should be changed with
> +.BR mount_setattr (2).
> +.P
> +The fields are as follows:
> +.TP
> +.I .attr_set
> +This field specifies which
> +.BI MOUNT_ATTR_ *
> +attribute flags to set.
> +.TP
> +.I .attr_clr
> +This fields specifies which
> +.BI MOUNT_ATTR_ *
> +attribute flags to clear.
> +.TP
> +.I .propagation
> +This field specifies what mount propagation will be applied.
> +The valid values of this field are the same propagation types described in
> +.BR mount_namespaces (7).
> +.TP
> +.I .userns_fd
> +This fields specifies a file descriptor that indicates which user namespace to

s/fields/field/

> +use as a reference for ID-mapped mounts with
> +.BR MOUNT_ATTR_IDMAP .
> +.SH VERSIONS
> +Extra fields may be appended to the structure,
> +with a zero value in a new field resulting in
> +the kernel behaving as though that extension field was not present.
> +Therefore, a user
> +.I must
> +zero-fill this structure on initialization.

I think this would be more appropriate for HISTORY.  In VERSIONS, we
usually document differences with the BSDs or other systems.

While moving this to HISTORY, it would also be useful to mention the
glibc version that added the structure.  In the future, we'd document
the versions of glibc and Linux that have added members.

> +.SH STANDARDS
> +Linux.
> +.SH SEE ALSO
> +.BR mount_setattr (2)

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)