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

["Günther Noack" <gnoack3000@gmail.com>]

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