[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-Id: <20250807-new-mount-api-v2-11-558a27b8068c@cyphar.com>
Date: Thu, 07 Aug 2025 03:44:45 +1000
From: Aleksa Sarai <cyphar@...har.com>
To: Alejandro Colomar <alx@...nel.org>
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>,
Aleksa Sarai <cyphar@...har.com>
Subject: [PATCH v2 11/11] fsconfig.2, mount_setattr.2: add note about
attribute-parameter distinction
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 <cyphar@...har.com>
---
man/man2/fsconfig.2 | 7 +++++++
man/man2/mount_setattr.2 | 37 +++++++++++++++++++++++++++++++++++++
2 files changed, 44 insertions(+)
diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2
index e2121b7a6b68..9e0e25acff3b 100644
--- a/man/man2/fsconfig.2
+++ b/man/man2/fsconfig.2
@@ -448,6 +448,13 @@ .SH HISTORY
Linux 5.2.
.\" commit ecdab150fddb42fe6a739335257949220033b782
glibc 2.36.
+.SH NOTES
+.SS Mount attributes and filesystem parameters
+For a description of the distinction between
+mount attributes and filesystem parameters,
+see the "Mount attributes and filesystem paramers" subsection
+of
+.BR mount_setattr (2).
.SH EXAMPLES
To illustrate the different kinds of flags that can be configured with
.BR fsconfig (),
diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index b9afc21035b8..3e6b59e5b57a 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2
@@ -790,6 +790,43 @@ .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)
+are also filesystem parameters.
+For example, the
+.I -o ro
+option to
+.BR mount (8)
+can refer to the
+"read-only" filesystem parameter,
+or the "read-only" mount attribute.
+.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).
+.\"
.SS Extensibility
In order to allow for future extensibility,
.BR mount_setattr ()
--
2.50.1
Powered by blists - more mailing lists