Re: [PATCH 2/4] man/man[27]/{landlock_create_ruleset.2,landlock.7}: Document LANDLOCK_CREATE_RULESET_ERRATA

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3140 bytes --]

Hi Günther,

On 2026-04-13T21:34:46+0200, Günther Noack wrote:
> Document the LANDLOCK_CREATE_RULESET_ERRATA flag, which returns a
> bitmask of fixed issues for the current Landlock ABI version.
> 
> This mechanism was introduced in Linux 6.15, but backported to all
> older kernel releases where these errata fixes were backported to.
> On official Linux kernel releases, if landlock_create_ruleset() with
> LANDLOCK_CREATE_RULESET_ERRATA returns an error, this is equivalent to
> the case where none of the known errata have been fixed.
> 
> Signed-off-by: Günther Noack <gnoack3000@gmail.com>
> ---
>  man/man2/landlock_create_ruleset.2 | 25 ++++++++++++++++++++++++-
>  1 file changed, 24 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index 7bca831cbd65..90d0341d2682 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -129,11 +129,34 @@ version.
>  Unless noted otherwise,
>  all features documented in these man pages are available with the
>  version 1.
> +.TP
> +.B LANDLOCK_CREATE_RULESET_ERRATA
> +If
> +.I attr
> +is NULL and
> +.I size
> +is 0,

You don't say what happens otherwise.  Is it an error?  If so, you
should say so; or rather, specify that they must be NULL and 0, instead
of having a condition.

> then the returned value is a bitmask of fixed issues
> +for the current Landlock ABI version.
> +If bit N is set (i.e.,
> +.IR "errata & (1 << (N - 1))" ),
> +then erratum N has been fixed in the running kernel.

Are those bits documented anywhere?

> +.IP
> +In addition to ABI versions, Landlock's errata mechanism tracks fixes

Please use semantic newlines.

> +for issues that may affect backwards compatibility
> +or require userspace awareness.

I'd reflow the above as:

	In addition to ABI versions,
	Landlock's errata mechanism
	tracks fixes for issues that
	may affect backwards compatibility
	or require user-space awareness.

> +.IP
> +Only check errata if your application specifically relies on behavior
> +that changed due to the fix.

> +The fixes generally make Landlock less restrictive or more correct,
> +not more restrictive.

This sentence seems inconsistent.  Is more correct the same as less
restrictive?  Otherwise, more correct could imply more restrictive in
some cases.  If more correct *always* means less restrictive, it should
be parenthesized.  If it doesn't, then I'm not convinced by the
sentence.

> +.IP
> +This flag is available on Linux versions where errata were fixed.

Is it possible that future Linux versions don't have any errata that
were fixed?  If so, does this mean that it won't be available then?


Have a lovely night!
Alex

>  .SH RETURN VALUE
>  On success,
>  .BR landlock_create_ruleset ()
>  returns a new Landlock ruleset file descriptor,
> -or a Landlock ABI version,
> +a Landlock ABI version,
> +or a Landlock errata bitmask,
>  according to
>  .IR flags .
>  On error,
> -- 
> 2.53.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]