Re: [PATCH v4 10/10] man/man2/{fsconfig,mount_setattr}.2: add note about attribute-parameter distinction
From: Alejandro Colomar <alx@kernel.org>
Date: 2025-09-21 09:59:09
Also in:
linux-fsdevel, linux-man, lkml
Hi Aleksa, On Fri, Sep 19, 2025 at 11:59:51AM +1000, Aleksa Sarai wrote:
quoted hunk ↗ jump to hunk
This was not particularly well documented in mount(8) nor mount(2), and since this is a fairly notable aspect of the new mount API, we should probably add some words about it. Signed-off-by: Aleksa Sarai <redacted> --- man/man2/fsconfig.2 | 12 ++++++++++++ man/man2/mount_setattr.2 | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+)diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2 index 5a18e08c700ac93aa22c341b4134944ee3c38d0b..d827a7b96e08284fb025f94c3348a4acc4571b7d 100644 --- a/man/man2/fsconfig.2 +++ b/man/man2/fsconfig.2@@ -579,6 +579,18 @@ .SS Generic filesystem parameters Linux Security Modules (LSMs) are also generic with respect to the underlying filesystem. See the documentation for the LSM you wish to configure for more details. +.SS Mount attributes and filesystem parameters +Some filesystem parameters +(traditionally associated with +.BR mount (8)-style +options) +have a sibling mount attribute +with superficially similar user-facing behaviour. +.P +For a description of the distinction between +mount attributes and filesystem parameters, +see the "Mount attributes and filesystem parameters" subsection of +.BR mount_setattr (2). .SH CAVEATS .SS Filesystem parameter types As a result ofdiff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2 index b27db5b96665cfb0c387bf5b60776d45e0139956..f7d0b96fddf97698e36cab020f1d695783143025 100644 --- a/man/man2/mount_setattr.2 +++ b/man/man2/mount_setattr.2@@ -790,6 +790,46 @@ .SS ID-mapped mounts .BR chown (2) system call changes the ownership globally and permanently. .\" +.SS Mount attributes and filesystem parameters +Some mount attributes +(traditionally associated with +.BR mount (8)-style +options) +have a sibling mount attribute +with superficially similar user-facing behaviour. +For example, the +.I -o ro
As said in another page, this should be .I \-o\~ro
+option to
+.BR mount (8)
+can refer to the
+"read-only" filesystem parameter,
+or the "read-only" mount attribute.
+Both of these result in mount objects becoming read-only,
+but they do have different behaviour.
+.P
+The distinction between these two kinds of option is that
+mount object attributes are applied per-mount-object
+(allowing different mount objects
+derived from a given filesystem instance
+to have different attributes),
+while filesystem instance parameters
+("superblock flags" in kernel-developer parlance)
+apply to all mount objects
+derived from the same filesystem instance.
+.P
+When using
+.BR mount (2),
+the line between these two types of mount options was blurred.
+However, with
+.BR mount_setattr ()
+and
+.BR fsconfig (2),
+the distinction is made much clearer.
+Mount attributes are configured with
+.BR mount_setattr (),
+while filesystem parameters can be configured using
+.BR fsconfig (2).
+.\"LGTM. I've finished with the review of the patch set. It's quite good. :) Have a lovely day! Alex
.SS Extensibility In order to allow for future extensibility, .BR mount_setattr () -- 2.51.0
-- <https://www.alejandro-colomar.es> Use port 80 (that is, <...:80/>).
Attachments
- signature.asc [application/pgp-signature] 833 bytes