[PATCH v5 8/8] man/man2/{fsconfig,mount_setattr}.2: add note about attribute-parameter distinction
From: Aleksa Sarai <hidden>
Date: 2025-09-24 15:32:48
Also in:
linux-fsdevel, linux-man, lkml
Subsystem:
the rest · Maintainer:
Linus Torvalds
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 | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+)
diff --git a/man/man2/fsconfig.2 b/man/man2/fsconfig.2
index a2d844a105c74f17af640d6991046dbd5fa69cf0..3b972761196b9c1577a6f324a2f4135471dd0ab3 100644
--- a/man/man2/fsconfig.2
+++ b/man/man2/fsconfig.2@@ -580,6 +580,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 of
diff --git a/man/man2/mount_setattr.2 b/man/man2/mount_setattr.2
index 2f8a79dfde722b7b58b80797d89798076af94f55..efe22496be95383b986d9a3623324d472a76c189 100644
--- a/man/man2/mount_setattr.2
+++ b/man/man2/mount_setattr.2@@ -792,6 +792,45 @@ .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 filesystem parameter +with superficially similar user-facing behaviour. +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. +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 are configured using +.BR fsconfig (2). .SS Extensibility In order to allow for future extensibility, .BR mount_setattr ()
--
2.51.0