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

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

[Günther Noack]

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

[PATCH 01/24] man/man7/unix.7: ERRORS: EINVAL: The address field is sun_family, not sun_type

[Günther Noack]

struct sockaddr_un has no sun_type field; the address family is in
sun_family, as described in "Address format" above.  The check is done
by unix_validate_addr() in linux.git net/unix/af_unix.c.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Fixes an obvious typo

 man/man7/unix.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index f9db05a71d93..75e125c61673 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -663,7 +663,7 @@ Invalid argument passed.
 A common cause is that the value
 .B AF_UNIX
 was not specified in the
-.I sun_type
+.I sun_family
 field of passed addresses, or the socket was in an
 invalid state for the applied operation.
 .TP
-- 
2.56.0

[PATCH 02/24] man/man7/unix.7: Socket options: SOL_SOCKET is a level, not a family

[Günther Noack]

SOL_SOCKET is passed as the "level" argument of getsockopt(2) and
setsockopt(2); it is not a socket family.  See setsockopt(2).

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Obvious terminology confusion, compare getsockopt(2)

 man/man7/unix.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 75e125c61673..1a94b00c6783 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -271,7 +271,7 @@ and read with
 .BR getsockopt (2)
 by specifying
 .B SOL_SOCKET
-as the socket family.
+as the level.
 .TP
 .B SO_PASSCRED
 Enabling this socket option causes receipt of the credentials of
-- 
2.56.0

[PATCH 03/24] man/man7/unix.7: SO_PASSCRED: ffix

[Günther Noack]

Only SCM_CREDENTIALS should be set in bold, not the following word.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    This looked unintended.

 man/man7/unix.7 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 1a94b00c6783..1054d7f52a30 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -276,7 +276,8 @@ as the level.
 .B SO_PASSCRED
 Enabling this socket option causes receipt of the credentials of
 the sending process in an
-.B SCM_CREDENTIALS ancillary
+.B SCM_CREDENTIALS
+ancillary
 message in each subsequently received message.
 The returned credentials are those specified by the sender using
 .BR SCM_CREDENTIALS ,
-- 
2.56.0

[PATCH 04/24] man/man7/sock_diag.7: Fix member order of struct unix_diag_vfs

[Günther Noack]

In the kernel's <linux/unix_diag.h>, udiag_vfs_ino comes before
udiag_vfs_dev, and it has been that way since the structure was added
in linux.git 5f7b0569460b ("unix_diag: Unix inode info NLA").  Both
members are __u32, so code written after the manual page would silently
mix up the inode and the device number.

Also reorder the member descriptions to match.

Fixes: 4f6a0a4a (2016-12-07; "sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface")
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Compared against unix_diag.h header,
    where the struct field order is different.

 man/man7/sock_diag.7 | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index d4e78c46cc8d..35a6d5a80ffc 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -180,8 +180,8 @@ structure:
 .in +4n
 .EX
 struct unix_diag_vfs {
-    __u32 udiag_vfs_dev;
     __u32 udiag_vfs_ino;
+    __u32 udiag_vfs_dev;
 };
 .EE
 .in
@@ -189,11 +189,11 @@ struct unix_diag_vfs {
 The fields of this structure are as follows:
 .RS
 .TP
-.I udiag_vfs_dev
-The device number of the corresponding on-disk socket inode.
-.TP
 .I udiag_vfs_ino
 The inode number of the corresponding on-disk socket inode.
+.TP
+.I udiag_vfs_dev
+The device number of the corresponding on-disk socket inode.
 .RE
 .TP
 .B UDIAG_SHOW_PEER
-- 
2.56.0

[PATCH 05/24] man/man7/sock_diag.7: udiag_wqueue: This is memory in use, not memory available

[Günther Noack]

For non-listening sockets, sk_diag_show_rqlen() in linux.git
net/unix/diag.c sets udiag_wqueue to unix_outq_len(), which returns
sk_wmem_alloc_get(): the send-buffer memory currently charged to queued
outgoing data.  The value grows as data is queued; it is not the amount
of space remaining.

Fixes: 4f6a0a4a (2016-12-07; "sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface")
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Verified in kernel code; the udiag_wqueue field does indeed have these
    different semantics -- it's the data already sent, which is still
    stuck in the output queue, not the maximum size of the output queue.

 man/man7/sock_diag.7 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index 35a6d5a80ffc..8f8b28b4404d 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -248,7 +248,9 @@ the backlog size which equals to the value passed as the second argument to
 .BR listen (2).
 .IP
 For established sockets:
-the amount of memory available for sending.
+the amount of memory currently allocated for data
+that was sent on this socket
+but has not yet been received by the peer.
 .RE
 .TP
 .B UDIAG_SHOW_MEMINFO
-- 
2.56.0

[PATCH 06/24] man/man7/unix.7: ERRORS: EPROTONOSUPPORT: Protocol 0 is also accepted

[Günther Noack]

unix_create() in linux.git net/unix/af_unix.c only fails if
'protocol && protocol != PF_UNIX'.  0 is the usual value, and the one
used in the SYNOPSIS.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    I double checked it in the code.

 man/man7/unix.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 1054d7f52a30..9df4d3b6f635 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -708,7 +708,7 @@ or
 .BR sendmsg (2).
 .TP
 .B EPROTONOSUPPORT
-Passed protocol is not
+Passed protocol is neither 0 nor
 .BR AF_UNIX .
 .TP
 .B EPROTOTYPE
-- 
2.56.0

[PATCH 07/24] man/man7/unix.7: ERRORS: ETOOMANYREFS: Fix the conditions

[Günther Noack]

The ETOOMANYREFS error is detected in too_many_unix_fds() in
net/unix/af_unix.c when the user's (not the processes') in-flight FDs
exceed RLIMIT_NOFILE, and the process has neither CAP_SYS_RESOURCE nor
CAP_SYS_ADMIN.

The check was introduced in linux.git 712f4aad406b ("unix: properly
account for FDs passed over unix sockets").

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Double checked in code -- the condition under which this error is
    returned was not fully spelled out.

 man/man7/unix.7 | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 9df4d3b6f635..86e72d0f58d4 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -732,10 +732,14 @@ when sending a file descriptor as ancillary data over
 a UNIX domain socket (see the description of
 .BR SCM_RIGHTS ,
 above).
-It occurs if the number of "in-flight" file descriptors exceeds the
+It occurs if the number of "in-flight" file descriptors
+sent by processes of the caller's real user ID
+exceeds the caller's
 .B RLIMIT_NOFILE
-resource limit and the caller does not have the
+resource limit and the caller has neither the
 .B CAP_SYS_RESOURCE
+nor the
+.B CAP_SYS_ADMIN
 capability.
 An in-flight file descriptor is one that has been sent using
 .BR sendmsg (2)
-- 
2.56.0

[PATCH 08/24] man/man7/socket.7: SO_PEEK_OFF: This option is no longer specific to unix(7)

[Günther Noack]

The option is implemented through proto_ops->set_peek_off, which is
nowadays also set for UDP and TCP sockets:

	linux.git 627d2d6b5500 ("udp: enable MSG_PEEK at non-zero offset")
		Linux 4.7, UDP over IPv4 and IPv6
	linux.git 05ea491641d3 ("tcp: add support for SO_PEEK_OFF socket option")
		Linux 6.10, TCP over IPv4
	linux.git be9a4fb831b8 ("tcp: add SO_PEEK_OFF socket option tor TCPv6")
		Linux 6.12, TCP over IPv6

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Double checked in code -- this feature has been added to these other
    protocols since that man page section was written; I made sure that we
    have all relevant commits listed as comments in the man page source.

 man/man7/socket.7 | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/man/man7/socket.7 b/man/man7/socket.7
index 96f6f173a40b..ebe0264d7ae4 100644
--- a/man/man7/socket.7
+++ b/man/man7/socket.7
@@ -662,14 +662,24 @@ For more information, see
 .TP
 .BR SO_PEEK_OFF " (since Linux 3.4)"
 .\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54
-This option, which is currently supported only for
-.BR unix (7)
-sockets, sets the value of the "peek offset" for the
+This option sets the value of the "peek offset" for the
 .BR recv (2)
 system call when used with
 .B MSG_PEEK
 flag.
 .IP
+This option is supported for
+.\" commit f55bb7f9cb82dec2f2e803d7bd0fc5929248e4d8
+.BR unix (7)
+sockets since Linux 3.4,
+.\" commit 627d2d6b550094d88f9e518e15967e7bf906ebbf
+for UDP sockets since Linux 4.7,
+and for TCP sockets since
+.\" commit 05ea491641d338422edbd87af3b311c16ea762f5
+Linux 6.10 (IPv4) and
+.\" commit be9a4fb831b8b6dc5724dd3e61973ea91b413ec1
+Linux 6.12 (IPv6).
+.IP
 When this option is set to a negative value
 (it is set to \-1 for all new sockets),
 traditional behavior is provided:
-- 
2.56.0

[PATCH 09/24] man/man7/unix.7: SO_PEERCRED: Also works for SOCK_SEQPACKET

[Günther Noack]

SOCK_SEQPACKET sockets use unix_stream_connect() as their connect
operation (see unix_seqpacket_ops in linux.git net/unix/af_unix.c), and
that function records the peer credentials for both ends.
unix_socketpair() records them for socket pairs of every type.

Connected SOCK_DGRAM sockets (unix_dgram_connect()) still don't record
peer credentials, so those remain excluded.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Double checked in code.
    
    The unix(7) SOCK_SEQPACKET socket type is also connection-oriented and
    shares the "connect" logic with SOCK_STREAM sockets.

 man/man7/unix.7 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 86e72d0f58d4..8fd29131ce48 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -342,9 +342,9 @@ feature test macro to obtain the definition of that structure from
 .IP
 The use of this option is possible only for connected
 .B AF_UNIX
-stream sockets and for
+stream and sequenced-packet sockets, and for
 .B AF_UNIX
-stream and datagram socket pairs created using
+socket pairs created using
 .BR socketpair (2).
 .\"
 .SS Autobind feature
-- 
2.56.0

[PATCH 10/24] man/man7/unix.7: SIOCINQ: Document behavior for SOCK_SEQPACKET

[Günther Noack]

unix_inq_len() in linux.git net/unix/af_unix.c handles all of
SOCK_SOCKET, SOCK_DGRAM and also SOCK_SEQPACKET

* Document SOCK_SEQPACKET, which sums up the lengths of all messages
  in the receive queue.
* Restructure sentence order, so that socket type differences are
  discussed in on paragraph, and commonalities in the next.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Double checked in code:
    
    unix_inq_len() first rejects listening sockets, then has a case
    analysis for the three socket types.
    
    The LLM initially just slapped an additional sentence into the
    paragraph, but that was mixing the socket-type-specific concerns with
    the general description -- I split that paragraph apart so that we
    have one paragraph for the three socket types and one for the
    socket-type-independent description.

 man/man7/unix.7 | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 8fd29131ce48..4d431ec6deaf 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -606,6 +606,19 @@ can be:
 For
 .B SOCK_STREAM
 sockets, this call returns the number of unread bytes in the receive buffer.
+For
+.B SOCK_DGRAM
+sockets,
+the returned value is the same as
+for Internet domain datagram sockets;
+see
+.BR udp (7).
+For
+.B SOCK_SEQPACKET
+sockets,
+this call returns the total number of bytes
+in all messages queued in the receive buffer.
+.IP
 The socket must not be in LISTEN state, otherwise an error
 .RB ( EINVAL )
 is returned.
@@ -625,13 +638,6 @@ defined in
 .\" That number is normally larger than the number of bytes of pending
 .\" output.  Since this info is, from userland's point of view, imprecise,
 .\" and it may well change, probably best not to document this now.
-For
-.B SOCK_DGRAM
-sockets,
-the returned value is the same as
-for Internet domain datagram sockets;
-see
-.BR udp (7).
 .SH ERRORS
 .TP
 .B EADDRINUSE
-- 
2.56.0

[PATCH 11/24] man/man7/sock_diag.7: udiag_states: Document TCP_CLOSE

[Günther Noack]

UNIX sockets can also be in the TCP_CLOSE state and it is possible to
query for that with sock_diag's udiag_states.  Document that in the
description of unix_diag_req (for querying) and unix_diag_msg (for the
response).

The implementaiton is in linux.git net/unix/diag.c, where
unix_diag_dump() filters on 'req->udiag_states & (1 << sk->sk_state)'.

Fixes: 4f6a0a4a (2016-12-07; "sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface")
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    The full list of "supported" states here is technically more of an
    implementation artifact -- the supported states are simply the states
    that a UNIX socket can assume.  So the kernel code does not explicitly
    check that anywhere, it's just documenting the states that can exist
    in practice.
    
    The initial LLM phrasing had added a section going into detail about
    the reasons why a socket might be in TCP_CLOSE state, but it felt like
    that was anyway obvious, and the phrasing was a bit vague in that it
    only gave an example.  I deleted that sentence and only kept the part
    that adds the mention of TCP_CLOSE.

 man/man7/sock_diag.7 | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index 8f8b28b4404d..20733cb8c8ae 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -151,6 +151,9 @@ Supported values are:
 .P
 1 <<
 .B TCP_LISTEN
+.P
+1 <<
+.B TCP_CLOSE
 .RE
 .TP
 .I udiag_ino
@@ -307,9 +310,10 @@ or
 .TP
 .I udiag_state
 This is set to one of
-.B TCP_LISTEN
+.BR TCP_LISTEN ,
+.BR TCP_ESTABLISHED ,
 or
-.BR TCP_ESTABLISHED .
+.BR TCP_CLOSE .
 .TP
 .I pad
 This field is set to 0.
-- 
2.56.0

[PATCH 12/24] man/man7/sock_diag.7: UNIX_DIAG_NAME: The payload is not always a pathname

[Günther Noack]

sk_diag_dump_name() in linux.git net/unix/diag.c copies the sun_path
part of the bound address, with length
'addr->len - offsetof(struct sockaddr_un, sun_path)'.  For abstract
sockets this starts with a null byte and is not a pathname; for
pathname sockets, the stored length includes the terminating null byte.
For sockets without an address, the attribute is omitted.

Fixes: 4f6a0a4a (2016-12-07; "sock_diag.7: New page documenting NETLINK_SOCK_DIAG interface")
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Shortened and simplified the LLM phrasing, which initially also
    explained the possible valid ways of populating sun_path.  That is
    already adequately explained in unix(7), so I removed that and linked
    unix(7) instead.

 man/man7/sock_diag.7 | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index 20733cb8c8ae..9a2b54a67b30 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -169,10 +169,14 @@ attribute as described below:
 .B UDIAG_SHOW_NAME
 The attribute reported in answer to this request is
 .BR UNIX_DIAG_NAME .
-The payload associated with this attribute is the pathname to which
-the socket was bound (a sequence of bytes up to
+The payload associated with this attribute is the
+.I sun_path
+part of the address to which the socket was bound
+(a sequence of bytes up to
 .B UNIX_PATH_MAX
-size).
+size, see
+.BR unix (7)).
+This attribute is not reported for unbound sockets.
 .TP
 .B UDIAG_SHOW_VFS
 The attribute reported in answer to this request is
-- 
2.56.0

[PATCH 13/24] man/man7/sock_diag.7: Document UDIAG_SHOW_UID

[Günther Noack]

linux.git cae9910e7344 ("net: Add UNIX_DIAG_UID to Netlink UNIX socket
diagnostics."), first released in Linux 5.3, added the UDIAG_SHOW_UID
flag and the UNIX_DIAG_UID attribute.  sk_diag_dump_uid() in
net/unix/diag.c reports sk_uid(sk) as a uid_t, mapped with
from_kuid_munged() into the user namespace of the requesting netlink
socket.

Assisted-by: LLM
Cc: Felipe Gasper <felipe@felipegasper.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    This documents a missing sock_diag feature introduced in 2019.
    
    The phrasing mirrors the phrasing of adjacent sections about other
    features.

 man/man7/sock_diag.7 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man7/sock_diag.7 b/man/man7/sock_diag.7
index 9a2b54a67b30..c82b24fe1198 100644
--- a/man/man7/sock_diag.7
+++ b/man/man7/sock_diag.7
@@ -265,6 +265,16 @@ The attribute reported in answer to this request is
 .BR UNIX_DIAG_MEMINFO .
 The payload associated with this attribute is an array of __u32 values
 described below in the subsection "Socket memory information".
+.TP
+.BR UDIAG_SHOW_UID " (since Linux 5.3)"
+.\" commit cae9910e73446cac68a54e3a7b02aaa12b689026
+The attribute reported in answer to this request is
+.BR UNIX_DIAG_UID .
+The payload associated with this attribute is a
+.I uid_t
+value which is the user ID of the owner of the socket,
+as seen from the user namespace of the netlink socket
+that is used for the query.
 .P
 The following attributes are reported back without any specific request:
 .TP
-- 
2.56.0

[PATCH 14/24] man/man7/unix.7: Several items of the same type may be sent in one message

[Günther Noack]

__scm_send() in linux.git net/core/scm.c walks all control messages.
Each SCM_RIGHTS item is passed to scm_fp_copy(), which appends the file
descriptors to the existing scm_fp_list, and fails with EINVAL only if
the combined count exceeds SCM_MAX_FD.  On the receiving side,
scm_detach_fds() emits a single SCM_RIGHTS control message.  Each
SCM_CREDENTIALS item is validated, and overwrites the credentials of the
previous one.

Keep the recommendation as portability advice, and describe the Linux
behavior.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    The factual analysis in the commit message is correct.
    
    I kept the LLM phrasing; it did not seem overly wordy to me and the
    style is in line with the paragraph after it, which also documents
    Linux-only vs. portable APIs that way.

 man/man7/unix.7 | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 4d431ec6deaf..480a565f7d04 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -528,7 +528,24 @@ option must be enabled on the socket (see above).
 .P
 When sending ancillary data with
 .BR sendmsg (2),
-only one item of each of the above types may be included in the sent message.
+portable applications should include
+only one item of each of the above types in the sent message.
+On Linux,
+if several
+.B SCM_RIGHTS
+items are included,
+their file descriptors are combined into a single list,
+to which the
+.B SCM_MAX_FD
+limit applies as a whole,
+and the receiver gets them in a single
+.B SCM_RIGHTS
+item;
+if several
+.B SCM_CREDENTIALS
+items are included,
+each of them is checked,
+and the last one takes effect.
 .P
 At least one byte of real data should be sent when sending ancillary data.
 On Linux, this is required to successfully send ancillary data over
-- 
2.56.0

[PATCH 15/24] man/man2/bind.2: ERRORS: EACCES: Write permission on the directory is required

[Günther Noack]

In addition to the search permission, binding a named UNIX domain
socket requires write permission on the parent directory.  Bring the
wording in line with similar documentation for EACCES on other
syscalls such as mkdir(2), mknod(2), connect(2), link(2) and
rename(2).

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Reworded commit message and made sure that wording is in-line with
    other man pages.

 man/man2/bind.2 | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/man/man2/bind.2 b/man/man2/bind.2
index ccb77e553cb2..6838a9d164aa 100644
--- a/man/man2/bind.2
+++ b/man/man2/bind.2
@@ -150,7 +150,9 @@ The following errors are specific to UNIX domain
 sockets:
 .TP
 .B EACCES
-Search permission is denied on a component of the path prefix.
+Write permission is denied on the directory
+in which the socket would be created,
+or search permission is denied on a component of the path prefix.
 (See also
 .BR path_resolution (7).)
 .TP
-- 
2.56.0

[PATCH 16/24] man/man7/unix.7: Autobind: Fix when it happens, and mention SO_PASSPIDFD

[Günther Noack]

Autobind happens if either one of SO_PASSCRED/SO_PASSPIDFD is set and
either connect() or sendmsg() happens.  Mention SO_PASSPIDFD and
clarify that autobind does not happen immediately when setting these
socket options.

In linux.git net/unix/af_unix.c, the autobind is done by
unix_dgram_connect(), unix_stream_connect() and unix_dgram_sendmsg(),
if the socket has no address and unix_may_passcred() is true.

unix_may_passcred() is also true when SO_PASSPIDFD is set, which was
added in linux.git 5e2ff6704a27 ("scm: add SO_PASSPIDFD and SCM_PIDFD"),
Linux 6.5.

Also, the old text said "not yet connected", but the condition is
about the socket not being bound.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Rephrased the LLM-generated text so that the canonical description is
    in the "Autobind feature" section and the other place just refers to
    it.
    
    SO_PASSPIDFD is unfortunately not documented yet at this point in
    time, but it's still correct to mention it here.

 man/man7/unix.7 | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 480a565f7d04..e5cd2b888ca9 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -286,8 +286,14 @@ if the sender did not specify
 .B SCM_CREDENTIALS
 ancillary data.
 .IP
-When this option is set and the socket is not yet connected,
-a unique name in the abstract namespace will be generated automatically.
+When this option is set on a socket that is not bound to an address,
+the socket is autobound to a unique name in the abstract namespace
+when
+.BR connect (2)
+or
+.BR sendmsg (2)
+is called on it;
+see "Autobind feature", below.
 .IP
 The value given as an argument to
 .BR setsockopt (2)
@@ -355,10 +361,19 @@ call specifies
 as
 .IR sizeof(sa_family_t) ,
 .\" i.e., sizeof(short)
-or the
+or if
+.BR connect (2)
+or
+.BR sendmsg (2)
+is called on a socket that was
+not explicitly bound to an address
+and that has the
 .B SO_PASSCRED
-socket option was specified for a socket that was
-not explicitly bound to an address,
+or
+.\" commit 5e2ff6704a275be009be8979af17c52361b79b89
+.B SO_PASSPIDFD
+(since Linux 6.5)
+socket option enabled,
 then the socket is autobound to an abstract address.
 The address consists of a null byte
 followed by 5 bytes in the character set
-- 
2.56.0

[PATCH 17/24] man/man7/unix.7: SOCK_RAW is accepted as an alias for SOCK_DGRAM

[Günther Noack]

unix_create() in linux.git net/unix/af_unix.c does:

	case SOCK_RAW:
		sock->type = SOCK_DGRAM;
		fallthrough;
	case SOCK_DGRAM:

so both socket(AF_UNIX, SOCK_RAW, 0) and the equivalent socketpair()
invocation succeed and create datagram sockets.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    For completeness;
    
    It is more complete to spell it out, but on the other hand, people
    should not be passing the SOCK_RAW type when they really mean
    SOCK_DGRAM.  I'm on the fence about whether this is useful.  If you
    want to omit this one, it also feels reasonable.

 man/man7/unix.7 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index e5cd2b888ca9..787a48baa97a 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -39,6 +39,11 @@ and (since Linux 2.6.4)
 for a sequenced-packet socket that is connection-oriented,
 preserves message boundaries,
 and delivers messages in the order that they were sent.
+On Linux,
+.B SOCK_RAW
+.\" unix_create() in net/unix/af_unix.c
+is also accepted as an alias for
+.BR SOCK_DGRAM .
 .P
 UNIX domain sockets support passing file descriptors or process credentials
 to other processes using ancillary data.
-- 
2.56.0

[PATCH 18/24] man/man7/unix.7: SCM_SECURITY: This is not specific to SELinux

[Günther Noack]

Reword the description of SCM_SECURITY to not be specific to SELinux.

The security context is populated in scm_passec() in linux.git
net/core/scm.c, through the security_secid_to_secctx() LSM hook, which
is currently implemented by SELinux, Smack and AppArmor.

Also clarify the properties of the returned string:

* There is no NAME_MAX limit on the length; SELinux contexts can be
  longer than that.  If the control buffer is too small, put_cmsg()
  truncates the data and sets MSG_CTRUNC.

* Whether the string is null-terminated also depends on the LSM:
  SELinux includes the null byte in the length, but smack_to_secctx()
  in security/smack/smack_lsm.c uses strlen() and doesn't.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    I reworded the LLM phrasing slightly and rewrote the commit message.
    
    I'm open for feedback about whether this is going into too much detail
    about the properties of the returned string.  Linux does indeed not
    guarantee that this terminates with a NUL byte, nor that NAME_MAX is
    large enough to hold it.

 man/man7/unix.7 | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 787a48baa97a..ff5a90863378 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -307,7 +307,7 @@ and returned as the result of
 is an integer boolean flag.
 .TP
 .B SO_PASSSEC
-Enables receiving of the SELinux security label of the peer socket
+Enables receiving of the security label of the peer socket
 in an ancillary message of type
 .B SCM_SECURITY
 (see below).
@@ -534,13 +534,26 @@ message, the
 option must be enabled on the socket.
 .TP
 .B SCM_SECURITY
-Receive the SELinux security context (the security label)
-of the peer socket.
-The received ancillary data is a null-terminated string containing
+Receive the security context (the security label)
+of the peer socket,
+as provided by the active Linux Security Module (LSM),
+such as SELinux or Smack.
+The received ancillary data is a string containing
 the security context.
-The receiver should allocate at least
+Whether the string includes a terminating null byte
+depends on the LSM;
+the length of the data is given by the
+.I cmsg_len
+field.
+There is no fixed limit on the length of the security context;
+allocating
 .B NAME_MAX
-bytes in the data portion of the ancillary message for this data.
+bytes in the data portion of the ancillary message
+is usually enough.
+If the buffer is too small,
+the data is truncated and the
+.B MSG_CTRUNC
+flag is set (see below).
 .IP
 To receive the security context, the
 .B SO_PASSSEC
-- 
2.56.0

[PATCH 19/24] man/man7/unix.7: SO_PASSSEC: wfix

[Günther Noack]

Use "security context", as in the description of SCM_SECURITY.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man7/unix.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index ff5a90863378..ca862df7cd95 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -307,7 +307,7 @@ and returned as the result of
 is an integer boolean flag.
 .TP
 .B SO_PASSSEC
-Enables receiving of the security label of the peer socket
+Enables receiving of the security context of the peer socket
 in an ancillary message of type
 .B SCM_SECURITY
 (see below).
-- 
2.56.0

[PATCH 20/24] man/man7/unix.7: ERRORS: Document EACCES, EAGAIN, EMSGSIZE, ENOSPC, and EPERM

[Günther Noack]

These are all returned directly from linux.git net/unix/af_unix.c:

EACCES
	unix_find_bsd() checks path_permission(&path, MAY_WRITE) on the
	socket file of the remote address.  The rule was already described
	in prose, but the error was not listed.

EAGAIN
	unix_stream_connect() returns -EAGAIN when the listener's backlog
	is full and the socket is nonblocking (there is no EINPROGRESS for
	AF_UNIX).  unix_dgram_sendmsg() returns -EAGAIN when the receiver's
	queue is full and the send would block.

EMSGSIZE
	unix_dgram_sendmsg() fails if 'len > sk->sk_sndbuf - 32'.  This is
	the limit described in "Sockets API".

ENOSPC
	unix_autobind() fails when all 2^20 autobind names are taken.

EPERM
	unix_dgram_connect() and unix_dgram_sendmsg() fail if
	!unix_may_send(), that is, if the target datagram socket is
	connected to a socket other than the caller's.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Verified in code.  Kept LLM wording, which seemed OK.
    
    Remark:
    
    The case where the remote end is connected to a different socket is
    obscure, but still possible with Unix Domain Sockets, when a program
    first bind(2)s to a name, and then connect(2)s to another name.  Then
    that socket can be discovered by another process through the bound
    name, but sending a dgram fails if the sender is not the one that that
    socket has connected to.

 man/man7/unix.7 | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index ca862df7cd95..47f09f16d024 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -690,10 +690,25 @@ defined in
 .\" and it may well change, probably best not to document this now.
 .SH ERRORS
 .TP
+.B EACCES
+The caller does not have write permission on the socket file
+specified as the remote address to
+.BR connect (2)
+or
+.BR sendto (2)
+(see "Pathname socket ownership and permissions", above).
+.TP
 .B EADDRINUSE
 The specified local address is already in use or the filesystem socket
 object already exists.
 .TP
+.B EAGAIN
+The socket is nonblocking, and either
+.BR connect (2)
+was called on a stream or sequenced-packet socket
+and the backlog of the listening socket is full,
+or a datagram was sent to a socket whose receive queue is full.
+.TP
 .B EBADF
 This error can occur for
 .BR sendmsg (2)
@@ -729,6 +744,11 @@ invalid state for the applied operation.
 called on an already connected socket or a target address was
 specified on a connected socket.
 .TP
+.B EMSGSIZE
+The datagram to be sent is larger than the limit imposed by the
+.B SO_SNDBUF
+socket option (see "Sockets API", above).
+.TP
 .B ENFILE
 The system-wide limit on the total number of open files has been reached.
 .TP
@@ -740,6 +760,11 @@ did not exist.
 .B ENOMEM
 Out of memory.
 .TP
+.B ENOSPC
+The socket was to be autobound,
+but all autobind addresses are in use
+(see "Autobind feature", above).
+.TP
 .B ENOTCONN
 Socket operation needs a target address, but the socket is not connected.
 .TP
@@ -751,6 +776,13 @@ use the out-of-band data option.
 The sender passed invalid credentials in the
 .IR "struct ucred" .
 .TP
+.B EPERM
+.BR connect (2)
+or
+.BR sendto (2)
+specified a datagram socket as the remote address,
+but that socket is connected to a different socket.
+.TP
 .B EPIPE
 Remote socket was closed on a stream socket.
 If enabled, a
-- 
2.56.0

[PATCH 21/24] man/man7/unix.7: Abstract sockets are scoped to a network namespace

[Günther Noack]

Point out that abstract Unix Domain Sockets are visible within the
current network namespace.

Abstract addresses are looked up in the per-network-namespace hash table
(unix_find_abstract() -> unix_find_socket_byname(net, ...) in linux.git
net/unix/af_unix.c), as network_namespaces(7) already mentions.

Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Verified in code

 man/man7/unix.7 | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 47f09f16d024..8d1a53948f5b 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -262,6 +262,16 @@ has no effect on the accessibility of the socket.
 Abstract sockets automatically disappear when all open references
 to the socket are closed.
 .P
+Each network namespace has its own abstract socket namespace (see
+.BR network_namespaces (7)):
+a socket can connect or send to an abstract address
+only if the socket bound to that address
+is in the same network namespace.
+In contrast,
+pathname sockets are not confined to a network namespace;
+they can be reached from any network namespace
+in which the socket file is accessible.
+.P
 The abstract socket namespace is a nonportable Linux extension.
 .\"
 .SS Socket options
-- 
2.56.0

[PATCH 22/24] man/man7/unix.7: Remove mentions of unsupported out-of-band messaging

[Günther Noack]

Limited support for MSG_OOB was added in linux.git 314001f0bf92
(2021-08-04; "af_unix: Add OOB support").

Its removal was discussed in [1] but has so far not happened.

The support is conditional on the CONFIG_AF_UNIX_OOB kconfig option,
so stating that it is supported would also be wrong.

Link: [1] <https://lore.kernel.org/all/20240409225209.58102-1-kuniyu@amazon.com/>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    This one is authored from scratch by hand; in the initial version, the
    LLM spotted the inaccuracy and then proceeded to document the feature
    in full glory -- I think it would be the wrong call to propagate the
    use of a feature whose removal has been discussed already due to low
    usage and security issues. (See cover letter as well)

 man/man7/unix.7 | 13 ++-----------
 1 file changed, 2 insertions(+), 11 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 8d1a53948f5b..bcb58336a1d8 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -401,14 +401,6 @@ The change to 5 bytes came in Linux 2.3.15.)
 The following paragraphs describe domain-specific details and
 unsupported features of the sockets API for UNIX domain sockets on Linux.
 .P
-UNIX domain sockets do not support the transmission of
-out-of-band data (the
-.B MSG_OOB
-flag for
-.BR send (2)
-and
-.BR recv (2)).
-.P
 The
 .BR send (2)
 .B MSG_MORE
@@ -780,7 +772,8 @@ Socket operation needs a target address, but the socket is not connected.
 .TP
 .B EOPNOTSUPP
 Stream operation called on non-stream oriented socket or tried to
-use the out-of-band data option.
+use the out-of-band data option
+when it isn't supported.
 .TP
 .B EPERM
 The sender passed invalid credentials in the
@@ -883,8 +876,6 @@ at least one byte of nonancillary data in the same
 or
 .BR recvmsg (2)
 call.
-.P
-UNIX domain stream sockets do not support the notion of out-of-band data.
 .\"
 .SH BUGS
 When binding a socket to an address,
-- 
2.56.0

[PATCH 23/24] man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD

[Günther Noack]

These were added in linux.git 5e2ff6704a27 (2023-06-08; "scm: add
SO_PASSPIDFD and SCM_PIDFD") and 7b26952a91cf (2023-06-08; "net: core:
add getsockopt SO_PEERPIDFD"), both in Linux 6.5.  They are the PID
file descriptor counterparts of SO_PASSCRED/SCM_CREDENTIALS and
SO_PEERCRED.

SO_PASSPIDFD
	sk_setsockopt() and sk_getsockopt() in net/core/sock.c handle it
	as a boolean flag for AF_UNIX sockets (EOPNOTSUPP otherwise).
	Like SO_PASSCRED, it triggers autobind, which was already
	mentioned in "Autobind feature".

SCM_PIDFD
	scm_pidfd_recv() in net/core/scm.c creates the PID file
	descriptor from scm->pid, which is the PID given in the sender's
	SCM_CREDENTIALS, or the sender's own PID by default.  The fd is
	created with O_CLOEXEC by pidfd_prepare().  If pidfd_prepare()
	fails, its negative error number is put into the cmsg data.
	Sending SCM_PIDFD is rejected by __scm_send() (EINVAL).

	Since c679d17d3f2d (Linux 6.17; "af_unix: enable handing out
	pidfds for reaped tasks in SCM_PIDFD"), PIDFD_STALE is passed,
	so this also works for reaped processes.  Before that,
	pidfd_prepare() returned -EINVAL for them.

SO_PEERPIDFD
	sk_getsockopt() returns a PID file descriptor for sk_peer_pid,
	or fails with ENODATA if there is none.

	Since 20b70e58961b (Linux 6.16; "net, pidfs: enable handing out
	pidfds for reaped sk->sk_peer_pid"), this also works for reaped
	processes on AF_UNIX sockets.  Before that, it failed with
	EINVAL.

Cc: Alexander Mikhalitsyn <alexander@mihalicyn.com>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Cc: Eric Dumazet <edumazet@kernel.org>
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man7/unix.7 | 101 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 101 insertions(+)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index bcb58336a1d8..6283d455ffa9 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -316,6 +316,33 @@ and returned as the result of
 .BR getsockopt (2)
 is an integer boolean flag.
 .TP
+.BR SO_PASSPIDFD " (since Linux 6.5)"
+.\" commit 5e2ff6704a275be009be8979af17c52361b79b89
+Enabling this socket option causes receipt of a PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the sending process in an
+.B SCM_PIDFD
+ancillary message in each subsequently received message
+(see below).
+.IP
+As with
+.BR SO_PASSCRED ,
+when this option is set on a socket that is not bound to an address,
+the socket is autobound to a unique name in the abstract namespace
+when
+.BR connect (2)
+or
+.BR sendmsg (2)
+is called on it;
+see "Autobind feature", below.
+.IP
+The value given as an argument to
+.BR setsockopt (2)
+and returned as the result of
+.BR getsockopt (2)
+is an integer boolean flag.
+.TP
 .B SO_PASSSEC
 Enables receiving of the security context of the peer socket
 in an ancillary message of type
@@ -367,6 +394,43 @@ stream and sequenced-packet sockets, and for
 .B AF_UNIX
 socket pairs created using
 .BR socketpair (2).
+.TP
+.BR SO_PEERPIDFD " (since Linux 6.5)"
+.\" commit 7b26952a91cf65ff1cc867a2382a8964d8c0ee7d
+This read-only socket option returns a new PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the peer process connected to this socket.
+This is the process whose credentials are returned by
+.BR SO_PEERCRED .
+Unlike the PID returned by
+.BR SO_PEERCRED ,
+the PID file descriptor cannot come to refer to a different process
+if the peer process terminates and its PID is reused.
+.IP
+The argument to
+.BR getsockopt (2)
+is a pointer to an
+.IR int ,
+in which the PID file descriptor is returned.
+The close-on-exec flag
+.RB ( FD_CLOEXEC )
+is set on the new file descriptor.
+.IP
+If the socket has no peer process,
+.BR getsockopt (2)
+fails with the error
+.BR ENODATA .
+.IP
+Since Linux 6.16,
+.\" commit 20b70e58961b855e61f2c6a7a19a38a64ad1bed6
+a PID file descriptor is returned
+even if the peer process has already terminated and been reaped.
+Before Linux 6.16,
+.BR getsockopt (2)
+failed with the error
+.B EINVAL
+in this case.
 .\"
 .SS Autobind feature
 If a
@@ -535,6 +599,42 @@ message, the
 .B SO_PASSCRED
 option must be enabled on the socket.
 .TP
+.BR SCM_PIDFD " (since Linux 6.5)"
+.\" commit 5e2ff6704a275be009be8979af17c52361b79b89
+Receive a PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the sending process.
+The data portion contains a single
+.IR int .
+The PID file descriptor refers to the process whose PID would be
+received in an
+.B SCM_CREDENTIALS
+message;
+if the sender specified
+.B SCM_CREDENTIALS
+ancillary data,
+it refers to the process with the PID given there.
+The close-on-exec flag
+.RB ( FD_CLOEXEC )
+is set on the new file descriptor.
+.IP
+If the PID file descriptor cannot be created,
+the data portion contains a negative error number instead.
+Since Linux 6.17,
+.\" commit c679d17d3f2d895b34e660673141ad250889831f
+a PID file descriptor is created
+even if the sending process has already terminated and been reaped.
+Before Linux 6.17,
+.B \-EINVAL
+was received in this case.
+.IP
+This message cannot be sent;
+it is generated by the kernel.
+To receive it, the
+.B SO_PASSPIDFD
+option must be enabled on the socket.
+.TP
 .B SCM_SECURITY
 Receive the security context (the security label)
 of the peer socket,
@@ -1264,6 +1364,7 @@ see
 and
 .BR seccomp_unotify (2).
 .SH SEE ALSO
+.BR pidfd_open (2),
 .BR recvmsg (2),
 .BR sendmsg (2),
 .BR socket (2),
-- 
2.56.0

[PATCH 24/24] man/man7/unix.7: Document SO_PASSRIGHTS

[Günther Noack]

SO_PASSRIGHTS was added in linux.git 77cbe1a6d873 (2025-05-19;
"af_unix: Introduce SO_PASSRIGHTS."), in Linux 6.16.  It lets a
receiver refuse file descriptors passed with SCM_RIGHTS, so that an
untrusted peer cannot leave it with file descriptors whose final
close() blocks for a long time (for example, a file on a hung NFS
mount or a FUSE-controlled file).

The option is enabled by default (unix_create1()).  When the receiving
socket has it disabled, unix_dgram_sendmsg(), unix_stream_sendmsg(),
and queue_oob() fail with EPERM if the message carries file
descriptors.  The check happens at send time, so messages that are
already queued are unaffected.

Also add the new EPERM case to ERRORS.

Link: <https://uapi-group.org/kernel-features/#disabling-reception-of-scm_rights-for-af_unix-sockets>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Cc: Willem de Bruijn <willemb@google.com>
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
 man/man7/unix.7 | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 6283d455ffa9..fe3feaced07a 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -343,6 +343,35 @@ and returned as the result of
 .BR getsockopt (2)
 is an integer boolean flag.
 .TP
+.BR SO_PASSRIGHTS " (since Linux 6.16)"
+.\" commit 77cbe1a6d8730a07f99f9263c2d5f2304cf5e830
+This socket option controls whether the socket accepts
+file descriptors from its peers in
+.B SCM_RIGHTS
+ancillary messages (see below).
+It is enabled by default.
+When it is disabled,
+.BR sendmsg (2)
+calls that pass file descriptors to this socket
+fail with the error
+.BR EPERM .
+The option is checked when the message is sent;
+disabling it does not affect messages
+that are already queued on the socket.
+.IP
+Processes that do not expect to receive file descriptors
+can disable this option.
+Once the file descriptors have been passed,
+closing them is the responsibility of the receiving process,
+and this may block for a long time,
+for example for a file on an unresponsive network file system.
+.IP
+The value given as an argument to
+.BR setsockopt (2)
+and returned as the result of
+.BR getsockopt (2)
+is an integer boolean flag.
+.TP
 .B SO_PASSSEC
 Enables receiving of the security context of the peer socket
 in an ancillary message of type
@@ -886,6 +915,14 @@ or
 specified a datagram socket as the remote address,
 but that socket is connected to a different socket.
 .TP
+.B EPERM
+The sender passed file descriptors in an
+.B SCM_RIGHTS
+ancillary message,
+but the receiving socket has the
+.B SO_PASSRIGHTS
+option disabled.
+.TP
 .B EPIPE
 Remote socket was closed on a stream socket.
 If enabled, a
-- 
2.56.0