[PATCH v2 0/3] Document LANDLOCK_ACCESS_FS_RESOLVE_UNIX

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

Thanks for the review!

This documents the LANDLOCK_ACCESS_FS_RESOLVE_UNIX feature,
introduced in the upcoming Linux 7.1 (Landlock ABI v9).

I applied the suggestions unmodified in most cases.  For the ABI
versions, I used the same style as in the landlock_restrict_self(2)
manpage, which I like for its succinctness.

* Patch 1: should already be applied (including it just for
  completeness, because it's not reflected in the git.kernel.org
  mirror yet)

* Patch 2: Changes the ABI version style for existing documentation,
  this is fine to apply before Linux 7.1.

* Patch 3: Describes the new "resolve UNIX" functionality in Linux 7.1

–Günther

Change Log
==========

V2:
  - s/only applies/applies only/.
  - Use italics for "*" in LANDLOCK_SCOPE_*.
  - s/resolve attempt/resolution attempt/
  - ABI version indicators: Use cardinals for ABI versions, and refer
    to it next to tagged paragraph titles where possible.  Also,
    introduce an additional preparation commit to fix this up for the
    exitisting documentation.
  - Use C99 comments in source code example

V1: Initial version


Günther Noack (3):
  man/man7/landlock.7: Adapt compatibility in code example to ABI v8
  man/man7/landlock.7: Simplify references to ABI versions
  man/man7/landlock.7: Document LANDLOCK_ACCESS_FS_RESOLVE_UNIX (ABI v9)

 man/man7/landlock.7 | 75 ++++++++++++++++++++++++++++++---------------
 1 file changed, 51 insertions(+), 24 deletions(-)

Range-diff against v1:
1:  07b854876a09 = 1:  fd6de0eb416e man/man7/landlock.7: Adapt compatibility in code example to ABI v8
-:  ------------ > 2:  33b9972559c5 man/man7/landlock.7: Simplify references to ABI versions
2:  414c8fa8f643 ! 3:  a937ec4a113b man/man7/landlock.7: Document LANDLOCK_ACCESS_FS_RESOLVE_UNIX (ABI v9)
    @@ Commit message
     
      ## man/man7/landlock.7 ##
     @@ man/man7/landlock.7: whose implementations are safe and return the right error codes
    + .BR FICLONERANGE ,
    + .BR FIDEDUPERANGE )
      .RE
    - .IP
    - This access right is available since the fifth version of the Landlock ABI.
     +.TP
    -+.B LANDLOCK_ACCESS_FS_RESOLVE_UNIX
    ++.BR LANDLOCK_ACCESS_FS_RESOLVE_UNIX "  (since Landlock ABI version 9)"
     +Look up pathname UNIX
     +domain sockets
     +.RB ( unix (7)).
    @@ man/man7/landlock.7: whose implementations are safe and return the right error c
     +.BR sendmsg (2)
     +with an explicit recipient address.
     +.IP
    -+This access right only applies to connections to UNIX server sockets
    ++This access right applies only to connections to UNIX server sockets
     +which were created outside the newly created Landlock domain
     +(e.g., from within a parent domain or from an unrestricted process).
     +Newly created UNIX servers
    @@ man/man7/landlock.7: whose implementations are safe and return the right error c
     +In this regard,
     +.B LANDLOCK_ACCESS_FS_RESOLVE_UNIX
     +has the same semantics as the
    -+.B LANDLOCK_SCOPE_*
    ++.BI LANDLOCK_SCOPE_ *
     +flags.
     +.IP
    -+If a resolve attempt is denied,
    ++If a resolution attempt is denied,
     +the operation returns an
     +.B EACCES
     +error,
     +in line with other filesystem access rights
     +(but different to denials for abstract UNIX domain sockets).
    -+.IP
    -+This access right is available since the ninth version of the Landlock ABI.
      .P
      Whether an opened file can be truncated with
      .BR ftruncate (2)
    @@ man/man7/landlock.7: and only use the available subset of access rights:
     -    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v6: same            */
     -    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v7: same            */
     -    (LANDLOCK_ACCESS_FS_IOCTL_DEV << 1) \- 1,  /* v8: same            */
    -+    (LANDLOCK_ACCESS_FS_MAKE_SYM     << 1) \- 1,  /* v1                     */
    -+    (LANDLOCK_ACCESS_FS_REFER        << 1) \- 1,  /* v2: add "refer"        */
    -+    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  /* v3: add "truncate"     */
    -+    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  /* v4: TCP support        */
    -+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  /* v5: add "ioctl_dev"    */
    -+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  /* v6: same               */
    -+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  /* v7: same               */
    -+    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  /* v8: same               */
    -+    (LANDLOCK_ACCESS_FS_RESOLVE_UNIX << 1) \- 1,  /* v9: add "resolve_unix" */
    ++    (LANDLOCK_ACCESS_FS_MAKE_SYM     << 1) \- 1,  // v1
    ++    (LANDLOCK_ACCESS_FS_REFER        << 1) \- 1,  // v2: add "refer"
    ++    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  // v3: add "truncate"
    ++    (LANDLOCK_ACCESS_FS_TRUNCATE     << 1) \- 1,  // v4: TCP support
    ++    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v5: add "ioctl_dev"
    ++    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v6: same
    ++    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v7: same
    ++    (LANDLOCK_ACCESS_FS_IOCTL_DEV    << 1) \- 1,  // v8: same
    ++    (LANDLOCK_ACCESS_FS_RESOLVE_UNIX << 1) \- 1,  // v9: add "resolve_unix"
      };
      \&
      int abi = landlock_create_ruleset(NULL, 0,
-- 
2.54.0