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

["Mickaël Salaün" <mic@digikod.net>]

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
>