[PATCH 00/24] Documentation fixes in unix(7)

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

This patch set fixes a variety of inaccuracies in unix(7) and related
man pages, clarifies imprecise wording in some places, and adds
documentation for some features where documentation was missing.

Most parts of this patch set are unrelated to each other and can also
be applied selectively, if you would prefer to leave some parts out.

Some mentionworthy points about features that were missing or had out
of date documentation:

* Out of band messaging support (MSG_OOB):
  * This patch set removes a mention that MSG_OOB is *unsupported* in
    unix(7) on Linux, which was factually wrong.
  * unix(7) OOB support can be configured with CONFIG_AF_UNIX_OOB
    and is therefore not universally available.
  * [1] is to my knowledge the only known user - unspecified Oracle
    products.  This was in reply to an attempt where Kuniyuki Iwashima
    tried to remove the support.
  * More bugs/vulnerabilities have been discovered since [2].
  * I'm worried that documenting this (and incentivizing its use
    further) may be counterproductive.

* PIDFD passing support (SCM_PIDFD, SO_PASSPIDFD, SO_PEERPIDFD)
  * This feature complements SCM_CREDENTIALS/SO_PEERCRED in that it
    passed the remote PID as a PIDFD, side-stepping the PID reuse
    problem and making it race-free.
  * I added a commit towards the end documenting that.

* SO_PASSRIGHTS (since 6.16):
  * This default-on socket option controls whether the socket owner
    accepts file descriptors over SCM_RIGHTS.  When it is off, the
    sender gets an EPERM when they try.
  * Most people don't receive file descriptors and can turn this off.
  * When left on, the receiver process ends up being on the hook for
    closing these FDs, and it can happen implicitly.  When an attacker
    sends crafted file descriptors, this close operation can take long
    (flush-on-close() semantics) and keep the receiving process busy.

Some features that I did not document yet, but which are apparently
also missing:

  * Socket options:
    * SO_PEERGROUPS
    * SO_PEERSEC (should link to SO_PEERSEC(2const), I guess?)
    * SO_INQ / SCM_INQ?
    * SO_RIGHTS_NOTRUNC
    * Options inheritance across accept(2).
  * IOCTLS:
    * SIOCUNIXFILE (gives an O_PATH-style FD for the remote end)
    * SIOCOUTQ
    * SIOCATMARK

Meta-remark on LLM use:

This patch set was written with the help of a LLM, in line with a
verbally agreed exception discussed with Alejandro.  Because it is to
my knowledge the first LLM-assisted contribution, and for full
transparency, here are some details on how that went:

The prompts had roughly the following form:

1. "Discover the factual statements in the unix.7 man page and then
   double check them against the kernel implementation."
   * Then, as follow up prompt: "Fix these issues in order of how
     confident you are about the findings, in one commit each."
2. I asked it separately about the list of AF_UNIX features and socket
   options that are *not* documented in unix(7) (because that was not
   part of the original prompt).
3. I asked it to document the PIDFD-related options and SO_PASSRIGHTS,
   because these seemed important features that deserve more visibility.

For all prompts, the agent had access to the man page repository, the
Linux kernel repository, as well as to a skill file (markdown
instructions) summarizing the man page style as documented in
man-pages(7).

I then went through the list of patches, verified each against the
kernel source, and simplified wording where necessary.  By and large,
the wording was often good.  Corrections that I did often took the
form of dropping too much detail, and cases where it repeated
something in a place that should have been documented in a more
central place only and then referenced (e.g., the Autobinding section
in unix(7)).  A major correction I did was to keep it from documenting
the out-of-band messaging support (see reasoning above) -- I was
unsure whether that might be counterproductive to a potential
deprecation of that feature (but the agent admittedly did not have
that context).

Going through these patches by hand was as tedious as it sounds,
especially given that these agents also find issues that the human
prompter is unfamiliar with... but it's doable.  It makes me wonder
though whether it would be more productive to use this to flag it to
the people who forgot to document their features...

–Günther


[1] https://lore.kernel.org/all/bef45d8e-35b7-42e4-bf6c-768da5b6d8f2@oracle.com/
[2] https://projectzero.google/2025/08/from-chrome-renderer-code-exec-to-kernel.html


Günther Noack (24):
  man/man7/unix.7: ERRORS: EINVAL: The address field is sun_family, not
    sun_type
  man/man7/unix.7: Socket options: SOL_SOCKET is a level, not a family
  man/man7/unix.7: SO_PASSCRED: ffix
  man/man7/sock_diag.7: Fix member order of struct unix_diag_vfs
  man/man7/sock_diag.7: udiag_wqueue: This is memory in use, not memory
    available
  man/man7/unix.7: ERRORS: EPROTONOSUPPORT: Protocol 0 is also accepted
  man/man7/unix.7: ERRORS: ETOOMANYREFS: Fix the conditions
  man/man7/socket.7: SO_PEEK_OFF: This option is no longer specific to
    unix(7)
  man/man7/unix.7: SO_PEERCRED: Also works for SOCK_SEQPACKET
  man/man7/unix.7: SIOCINQ: Document behavior for SOCK_SEQPACKET
  man/man7/sock_diag.7: udiag_states: Document TCP_CLOSE
  man/man7/sock_diag.7: UNIX_DIAG_NAME: The payload is not always a
    pathname
  man/man7/sock_diag.7: Document UDIAG_SHOW_UID
  man/man7/unix.7: Several items of the same type may be sent in one
    message
  man/man2/bind.2: ERRORS: EACCES: Write permission on the directory is
    required
  man/man7/unix.7: Autobind: Fix when it happens, and mention
    SO_PASSPIDFD
  man/man7/unix.7: SOCK_RAW is accepted as an alias for SOCK_DGRAM
  man/man7/unix.7: SCM_SECURITY: This is not specific to SELinux
  man/man7/unix.7: SO_PASSSEC: wfix
  man/man7/unix.7: ERRORS: Document EACCES, EAGAIN, EMSGSIZE, ENOSPC,
    and EPERM
  man/man7/unix.7: Abstract sockets are scoped to a network namespace
  man/man7/unix.7: Remove mentions of unsupported out-of-band messaging
  man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD
  man/man7/unix.7: Document SO_PASSRIGHTS

 man/man2/bind.2      |   4 +-
 man/man7/sock_diag.7 |  40 ++++--
 man/man7/socket.7    |  16 ++-
 man/man7/unix.7      | 308 +++++++++++++++++++++++++++++++++++++------
 4 files changed, 316 insertions(+), 52 deletions(-)

-- 
2.56.0