Re: [PATCH v2 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: 3470 bytes --]

Hi Günther,

On 2026-04-21T00:35:15+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 | 57 ++++++++++++++++++++++++++----
>  1 file changed, 51 insertions(+), 6 deletions(-)
> 
> diff --git a/man/man2/landlock_create_ruleset.2 b/man/man2/landlock_create_ruleset.2
> index d4eb5d827656..a24a4dd6cbb3 100644
> --- a/man/man2/landlock_create_ruleset.2
> +++ b/man/man2/landlock_create_ruleset.2
> @@ -116,11 +116,7 @@ Otherwise,
>  can be set to:
>  .TP
>  .B LANDLOCK_CREATE_RULESET_VERSION
> -If
> -.I attr
> -is NULL and
> -.I size
> -is 0, then the returned value is the highest supported Landlock ABI version

This fix (and the related changes below) should be done in a separate
patch.

Other than that, this patch LGTM.


Have a lovely night!
Alex

> +Return the highest supported Landlock ABI version
>  (starting at 1).
>  This version can be used for a best-effort security approach,
>  which is encouraged when user space is not pinned to a specific kernel
> @@ -129,11 +125,50 @@ version.
>  Unless noted otherwise,
>  all features documented in these manual pages are available with the
>  version 1.
> +.TP
> +.B LANDLOCK_CREATE_RULESET_ERRATA
> +Return 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.
> +.IP
> +In addition to ABI versions,
> +Landlock's errata mechanism
> +tracks fixes for issues that
> +may affect backwards compatibility
> +or require userspace awareness.
> +.IP
> +Only check errata if your application specifically relies on behavior
> +that changed due to the fix.
> +.IP
> +The full list of Landlock errata is available at
> +.UR https:\://docs.kernel.org/userspace\-api/landlock.html#landlock\-errata
> +.UE .
> +.IP
> +This flag is available on all Linux versions
> +where Landlock errata were fixed.
> +This specifically includes
> +all newest bugfix releases
> +of stable kernels
> +where Landlock is supported.
> +.P
> +If
> +.B LANDLOCK_CREATE_RULESET_VERSION
> +or
> +.B LANDLOCK_CREATE_RULESET_ERRATA
> +is set,
> +then
> +.I attr
> +must be NULL and
> +.I size
> +must be 0.
>  .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 .
>  .P
> @@ -159,6 +194,16 @@ Unknown
>  or unknown access, or unknown scope, or too small
>  .IR size .
>  .TP
> +.B EINVAL
> +Non-NULL
> +.IR attr
> +or non-zero
> +.IR size
> +in combination with
> +.B LANDLOCK_CREATE_RULESET_VERSION
> +or
> +.BR LANDLOCK_CREATE_RULESET_ERRATA .
> +.TP
>  .B ENOMSG
>  Empty accesses (i.e.,
>  .I attr
> -- 
> 2.53.0
> 

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

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