[PATCH 1/5] landlock.7, landlock_*.2: Wording improvements

Günther Noack
2024-07-15T15:56:01Z

* Various wording fixes
* List the same error code multiple times,
if it can happen for multiple reasons.

Cc: Mickaël Salaün <mic@digikod.net>
Signed-off-by: Günther Noack <gnoack@google.com>
---
man/man2/landlock_add_rule.2 | 9 +++++++--
man/man2/landlock_create_ruleset.2 | 6 +++---
man/man2/landlock_restrict_self.2 | 11 ++++++-----
man/man7/landlock.7 | 6 ++++--
4 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/man/man2/landlock_add_rule.2 b/man/man2/landlock_add_rule.2
index d4ae8f2f6..fa0b1f109 100644
--- a/man/man2/landlock_add_rule.2
+++ b/man/man2/landlock_add_rule.2
@@ -60,7 +60,9 @@ struct landlock_path_beneath_attr {
.in
.IP
.I allowed_access
-contains a bitmask of allowed filesystem actions for this file hierarchy
+contains a bitmask of allowed filesystem actions,
+which can be applied on the given
+.I parent_fd
(see
.B Filesystem actions
in
@@ -92,7 +94,10 @@ Landlock is supported by the kernel but disabled at boot time.
.TP
.B EINVAL
.I flags
-is not 0, or the rule accesses are inconsistent (i.e.,
+is not 0.
+.TP
+.B EINVAL
+The rule accesses are inconsistent (i.e.,
.I rule_attr\->allowed_access
is not a subset of the ruleset handled accesses).
.TP
diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
index 618d54f37..871b91dcb 100644
--- a/man/man2/landlock_create_ruleset.2
+++ b/man/man2/landlock_create_ruleset.2
@@ -23,7 +23,8 @@ Standard C library
A Landlock ruleset identifies a set of rules (i.e., actions on objects).
This
.BR landlock_create_ruleset ()
-system call enables creating a new file descriptor identifying a ruleset.
+system call creates a new file descriptor
+which identifies a ruleset.
This file descriptor can then be used by
.BR landlock_add_rule (2)
and
@@ -45,8 +46,7 @@ struct landlock_ruleset_attr {
.in
.IP
.I handled_access_fs
-is a bitmask of actions that is handled by this ruleset and
-should then be forbidden if no rule explicitly allows them
+is a bitmask of handled filesystem actions
(see
.B Filesystem actions
in
diff --git a/man/man2/landlock_restrict_self.2 b/man/man2/landlock_restrict_self.2
index d4e5e753c..f044c6b31 100644
--- a/man/man2/landlock_restrict_self.2
+++ b/man/man2/landlock_restrict_self.2
@@ -20,7 +20,7 @@ Standard C library
.SH DESCRIPTION
Once a Landlock ruleset is populated with the desired rules, the
.BR landlock_restrict_self ()
-system call enables enforcing this ruleset on the calling thread.
+system call enforces this ruleset on the calling thread.
See
.BR landlock (7)
for a global overview.
@@ -38,10 +38,11 @@ with multiple independent rulesets coming from different sources
built-in application policy).
However, most applications should only need one call to
.BR landlock_restrict_self ()
-and they should avoid arbitrary numbers of such calls because of the
-composed rulesets limit.
-Instead, developers are encouraged to build a tailored ruleset thanks to
-multiple calls to
+and they should avoid arbitrary numbers of such calls
+because of the composed rulesets limit.
+Instead,
+developers are encouraged to build a single tailored ruleset
+with multiple calls to
.BR landlock_add_rule (2).
.P
In order to enforce a ruleset, either the caller must have the
diff --git a/man/man7/landlock.7 b/man/man7/landlock.7
index 4a98f6549..f7bb37cba 100644
--- a/man/man7/landlock.7
+++ b/man/man7/landlock.7
@@ -58,7 +58,7 @@ and
.BR landlock_create_ruleset (2)
for more context.
.P
-A file can only receive these access rights:
+The following access rights apply only to files:
.TP
.B LANDLOCK_ACCESS_FS_EXECUTE
Execute a file.
@@ -87,6 +87,9 @@ or
.BR open (2)
with
.BR O_TRUNC .
+.IP
+This access right is available since the third version of the Landlock ABI.
+.P
Whether an opened file can be truncated with
.BR ftruncate (2)
is determined during
@@ -97,7 +100,6 @@ using
.B LANDLOCK_ACCESS_FS_READ_FILE
and
.BR LANDLOCK_ACCESS_FS_WRITE_FILE .
-This access right is available since the third version of the Landlock ABI.
.P
A directory can receive access rights related to files or directories.
The following access right is applied to the directory itself,
--
2.45.2.993.g49e7a77208-goog