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

Mickaël Salaün
2024-07-16T14:38:10Z

On Mon, Jul 15, 2024 at 03:55:50PM +0000, Günther Noack wrote:
> * 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>

Reviewed-by: Mickaël Salaün <mic@digikod.net>

> ---
> 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
>