landlock: update Haddock comments according to new header

landlock/CHANGELOG.md

@@ -16,6 +16,8 @@
 
 * Properly zero-out structs after allocation.
 
+* Update `landlock.h` to Linux 6.8.
+
 ## 0.2.1.1 -- 2023-02-28
 
 * Extend API documentation with links to man-pages.

landlock/internal/System/Landlock/Flags.hs

@@ -142,27 +142,38 @@ data AccessFsFlag
     -- ([@LANDLOCK_ACCESS_FS_MAKE_SYM@](https://man.archlinux.org/man/landlock.7.en#LANDLOCK_ACCESS_FS_MAKE_SYM)).
     AccessFsMakeSym
   | -- | Link or rename a file from or to a different
-    --   directory (i.e. reparent a file hierarchy).  This access right is
-    --   available since the second version of the Landlock ABI.  This is also the
-    --   only access right which is always considered handled by any ruleset in
-    --   such a way that reparenting a file hierarchy is always denied by default.
-    --   To avoid privilege escalation, it is not enough to add a rule with this
-    --   access right.  When linking or renaming a file, the destination directory
-    --   hierarchy must also always have the same or a superset of restrictions of
-    --   the source hierarchy.  If it is not the case, or if the domain doesn't
-    --   handle this access right, such actions are denied by default with
-    --   [@errno@](https://man.archlinux.org/man/errno.3)
-    --   set to [@EXDEV@](https://man.archlinux.org/man/errno.3#EXDEV).  Linking
-    --   also requires a @LANDLOCK_ACCESS_FS_MAKE_*@ access right on the
-    --   destination directory, and renaming also requires a
-    --   @LANDLOCK_ACCESS_FS_REMOVE_*@ access right on the source's (file or
-    --   directory) parent.  Otherwise, such actions are denied with
-    --   [@errno@](https://man.archlinux.org/man/errno.3) set to
-    --   [@EACCES@](https://man.archlinux.org/man/errno.3#EACCES).
-    --   The [@EACCES@](https://man.archlinux.org/man/errno.3#EACCES)
-    --   [@errno@](https://man.archlinux.org/man/errno.3) prevails over
-    --   [@EXDEV@](https://man.archlinux.org/man/errno.3#EXDEV) to let user
-    --   space efficiently deal with an unrecoverable error.
+    -- directory (i.e. reparent a file hierarchy)
+    -- ([@LANDLOCK_ACCESS_FS_REFER@](https://man.archlinux.org/man/landlock.7.en#LANDLOCK_ACCESS_FS_REFER)).
+    --
+    -- This access right is available since the second version of the Landlock
+    -- ABI.
+    --
+    -- This is the only access right which is denied by default by any ruleset,
+    -- even if the right is not specified as handled at ruleset creation time.
+    -- The only way to make a ruleset grant this right is to explicitly allow it
+    -- for a specific directory by adding a matching rule to the ruleset.
+    --
+    -- In particular, when using the first Landlock ABI version, Landlock will
+    -- always deny attempts to reparent files between different directories.
+    --
+    -- In addition to the source and destination directories having the
+    -- @LANDLOCK_ACCESS_FS_REFER@ access right, the attempted link or rename
+    -- operation must meet the following constraints:
+    --
+    -- * The reparented file may not gain more access rights in the destination
+    --   directory than it previously had in the source directory.  If this is
+    --   attempted, the operation results in an [@EXDEV@](https://man.archlinux.org/man/errno.3#EXDEV) error.
+    --
+    -- * When linking or renaming, the @LANDLOCK_ACCESS_FS_MAKE_*@ right for the
+    --   respective file type must be granted for the destination directory.
+    --   Otherwise, the operation results in an [@EACCES@](https://man.archlinux.org/man/errno.3#EACCES) error.
+    --
+    -- * When renaming, the @LANDLOCK_ACCESS_FS_REMOVE_*@ right for the
+    --   respective file type must be granted for the source directory.  Otherwise,
+    --   the operation results in an [@EACCES@](https://man.archlinux.org/man/errno.3#EACCES) error.
+    --
+    -- If multiple requirements are not met, the [@EACCES@](https://man.archlinux.org/man/errno.3#EACCES) error code takes
+    -- precedence over [@EXDEV@](https://man.archlinux.org/man/errno.3#EXDEV).
     AccessFsRefer
   | -- | Truncate a file with
     -- [@truncate@](https://man.archlinux.org/man/truncate.2),