[PATCH v3] landlock: Expand restrict flags example for ABI version 8

[Panagiotis "Ivory" Vasilopoulos]

Add LANDLOCK_RESTRICT_SELF_TSYNC to the backwards compatibility example
for restrict flags. This introduces completeness, similar to that of
the ruleset attributes example. However, as the new example can impact
enforcement in certain cases, an appropriate warning is also included.

Additionally, I modified the two comments of the example to make them
more consistent with the ruleset attributes example's.

Signed-off-by: Panagiotis 'Ivory' Vasilopoulos <git@xxxxxxxxxxx>
Co-developed-by: Dan Cojocaru <dan@xxxxxxxx>
Signed-off-by: Dan Cojocaru <dan@xxxxxxxx>
---
Changes in v3:
- Add __attribute__((fallthrough)) like in earlier example.
- Improve comment for LANDLOCK_RESTRICT_SELF_TSYNC (ABI < 8) example.
- Add relevant warning for ABI < 8 example based on Günther's feedback.
- Link to v2: https://lore.kernel.org/r/20260221-landlock-docs-add-tsync-example-v2-1-60990986bba5@xxxxxxxxxxx

Changes in v2:
- Fix formatting error.
- Link to v1: https://lore.kernel.org/r/20260221-landlock-docs-add-tsync-example-v1-1-f89383809eb4@xxxxxxxxxxx
---
 Documentation/userspace-api/landlock.rst | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 13134bccdd39d78ddce3daf454f32dda162ce91b..b71ac7aa308260b8141e5d35248fb68cec6dcba9 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -196,13 +196,33 @@ similar backwards compatibility check is needed for the restrict flags
 (see sys_landlock_restrict_self() documentation for available flags):
 
 .. code-block:: c
-
-    __u32 restrict_flags = LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON;
-    if (abi < 7) {
-        /* Clear logging flags unsupported before ABI 7. */
+    __u32 restrict_flags =
+        LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON |
+        LANDLOCK_RESTRICT_SELF_TSYNC;
+    switch (abi) {
+    case 1 ... 6:
+        /* Clear logging flags unsupported for ABI < 7 */
         restrict_flags &= ~(LANDLOCK_RESTRICT_SELF_LOG_SAME_EXEC_OFF |
                             LANDLOCK_RESTRICT_SELF_LOG_NEW_EXEC_ON |
                             LANDLOCK_RESTRICT_SELF_LOG_SUBDOMAINS_OFF);
+        __attribute__((fallthrough));
+    case 7:
+        /* Removes multithreaded enforcement flag unsupported for ABI < 8 */
+        /*
+         * WARNING!
+         * Don't copy-paste this just yet! This example impacts enforcement
+         * and can potentially decrease protection if misused.
+         *
+         * Below ABI v8, a Landlock policy can only be enforced for the calling
+         * thread and its children. This behavior remains a default for ABI v8,
+         * but the flag ``LANDLOCK_RESTRICT_SELF_TSYNC`` can now be used to
+         * enforce policies across all threads of the calling process. If an
+         * application's Landlock integration was designed under the assumption
+         * that the flag is used (such as when children threads are responsible
+         * for enforcing and/or overriding policies of parents and siblings),
+         * removing said flag can decrease protection for older Linux versions.
+         */
+        restrict_flags &= ~LANDLOCK_RESTRICT_SELF_TSYNC;
     }
 
 The next step is to restrict the current thread from gaining more privileges

---
base-commit: ceb977bfe9e8715e6cd3a4785c7aab8ea5cd2b77
change-id: 20260221-landlock-docs-add-tsync-example-e8fd5c64a366

Best regards,
-- 
Panagiotis "Ivory" Vasilopoulos <git@xxxxxxxxxxx>