[PATCH v2 0/6] {unix,socket,bind}.7: General Unix Domain Socket fixes

[PATCH v2 0/6] {unix,socket,bind}.7: General Unix Domain Socket fixes

[Günther Noack]

Hello!

This is patch set (A) spun off from the "Documentation fixes in
unix(7)" patch set [1], which is now split into these three parts:

 (A) Miscellaneous fixes, mostly in unix.7, one in socket.7     <-- this one
 (B) Socket options and Socket-level Control Messages (SCM_*)
 (C) sock_diag.7

This patch set fixes miscellaneous inaccuracies and documents missing
error codes.  It applies cleanly on the current "master".

Thank you for your reviews of v1 and v2 of the still-joined patch set,
as well as of v1 of the split patch set.

Changes in v2 (split):

* Mention commit hashes in commit messages, not in groff comments
* In SIOCINQ docs, describe SOCK_STREAM and SOCK_SEQPACKET together
* s/Named Unix Domain Sockets/pathname Unix Domain Sockets/
* Abstract namespaces: Wording simplifications
* Error descriptions: Wording simplifications
* Dropped commits:
  * Drop the commit that documented SOCK_RAW as alias for SOCK_DGRAM
  * Drop the commit that documented the socket() "protocol" argument 0
    is acceptable to avoid EPROTONOSUPPORT
  * Drop commits that already made it into the master branch.

Changes in v1 (split):

* Some commit message rewording (especially quoted the kernel code
  more directly).
* In the Abstract UDS scoping commit below, reworded the subsequent
  paragraph sligthly to avoid confusion with the "namespace"
  terminology being used differently in adjacent paragraphs.
* I removed the commit that changed the wording about Out-of-Band
  messaging, per Kuniyuki's suggestion in [2].

v1: https://lore.kernel.org/all/20261021210800.27338-2-gnoack3000@gmail.com/

This patch set has been produced with the help of a LLM, which was
helpful for spotting a long list of inaccuracies, comparing the
documentation with the kernel implementation.  (More details in [1])

–Günther

[1] https://lore.kernel.org/all/20261018173712.27670-1-gnoack3000@gmail.com/
[2] https://lore.kernel.org/all/CAAVpQUBh+J-aBLbkpzT7qmt7B714O529HWcTuQsVLT4wLBnDJA@mail.gmail.com/


Günther Noack (6):
  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/unix.7: Explain Abstract UDS scoping to the network namespace
  man/man2/bind.2: ERRORS: EACCES: Write permission on the directory is
    required
  man/man7/unix.7: ERRORS: Document EACCES, EAGAIN, EMSGSIZE, ENOSPC,
    and EPERM

 man/man2/bind.2   |  4 ++-
 man/man7/socket.7 | 11 +++++---
 man/man7/unix.7   | 67 ++++++++++++++++++++++++++++++++++++++---------
 3 files changed, 66 insertions(+), 16 deletions(-)

-- 
2.56.0

[PATCH v2 1/6] 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 (2016-04-05; "udp: enable MSG_PEEK at non-zero offset")
		Linux 4.7, UDP over IPv4 and IPv6
	linux.git 05ea491641d3 (2024-04-11; "tcp: add support for SO_PEEK_OFF socket option")
		Linux 6.10, TCP over IPv4
	linux.git be9a4fb831b8 (2024-08-29; "tcp: add SO_PEEK_OFF socket option tor TCPv6")
		Linux 6.12, TCP over IPv6

Previously, it was only available for UNIX Domain Sockets:

	linux.git f55bb7f9cb82 (2012-02-21; "unix: Support peeking offset for datagram and seqpacket sockets")
        linux.git ef64a54f6e55 (2012-02-21; "sock: Introduce the SO_PEEK_OFF sock option")

Cc: Jon Maloy <jmaloy@redhat.com>
Cc: samanthakumar <samanthakumar@google.com>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Reviewed-by: Alejandro Colomar <alx@kernel.org>
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.
    
    The commits that introduced them are only listed in the commit
    message, not in the source, per Alejandro's request in [1].
    
    [1] https://lore.kernel.org/all/atulJkR7fAgyKhPP@debian/

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

diff --git a/man/man7/socket.7 b/man/man7/socket.7
index 96f6f173a40b..60133b4712eb 100644
--- a/man/man7/socket.7
+++ b/man/man7/socket.7
@@ -662,14 +662,19 @@ .SS Socket options
 .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
+.BR unix (7)
+sockets since Linux 3.4,
+for UDP sockets since Linux 4.7,
+and for TCP sockets since
+Linux 6.10 (IPv4) and 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 v2 2/6] 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 (as defined in the ops structure unix_seqpacket_ops in
linux.git net/unix/af_unix.c).  That function records the peer
credentials for both ends for later lookup.

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.

In the code, the function that initializes the peercred is
init_peercred()/update_peercred().

Fixes: 73b3a5686084 (2005-08-16; "Clarified details of use of SO_PEERCRED.")
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
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 1054d7f52a30..d0c1765dfd79 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -342,9 +342,9 @@ .SS Socket options
 .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 v2 3/6] man/man7/unix.7: SIOCINQ: Document behavior for SOCK_SEQPACKET

[Günther Noack]

Document the SIOCINQ behavior for 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.

For reference, the SIOCINQ lookup is implemented in
unix_inq_len() in linux.git net/unix/af_unix.c.

This function first rejects SIOCINQ for listening sockets with
-EINVAL, then does a case analysis for the three types of Unix Domain
Sockets:

For SOCK_STREAM, the result is:

	return READ_ONCE(unix_sk(sk)->inq_len);

For SOCK_SEQPACKET, the result is calculated using:

	skb_queue_walk(&sk->sk_receive_queue, skb)
        	amount += unix_skb_len(skb);

For SOCK_DGRAM, the result is:

	skb = skb_peek(&sk->sk_receive_queue);
	if (skb)
		amount = skb->len;

Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    I double checked this all in the code, and quoted the code.  Both the
    commit message and commit body were substantially edited based on the
    initial LLM-based version.  (Nevertheless, I would have likely missed
    the inaccuracy if the LLM hadn't found it.)
    
    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 | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index d0c1765dfd79..c370b021589a 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -605,7 +605,15 @@ .SS Ioctls
 .B SIOCINQ
 For
 .B SOCK_STREAM
+and
+.B SOCK_SEQPACKET
 sockets, this call returns the number of unread bytes in the receive buffer.
+For
+.B SOCK_DGRAM
+sockets,
+this call returns size of the next pending datagram,
+or 0 when no datagram is pending.
+.IP
 The socket must not be in LISTEN state, otherwise an error
 .RB ( EINVAL )
 is returned.
@@ -625,13 +633,6 @@ .SS Ioctls
 .\" 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 v2 4/6] man/man7/unix.7: Explain Abstract UDS scoping to the network namespace

[Günther Noack]

Point out that Abstract Unix Domain Sockets are visible within the
current network namespace, unlike pathname Unix Domain Sockets, where
the remote socket is looked up through the mount namespace.

To avoid confusion, remove the word "namespace" from the subsequent
paragraph, where it is used in a more colloquial form (there is no
abstract socket namespace in the sense of namespaces(7)).

This is already described in network_namespaces(7) as well, but might
be mentionworthy here too.

The lookup of Abtract addresses happens in __unix_find_socket_byname()
in linux.git net/unix/af_unix.c, where it is looked up in the network
namespace (struct net *net) in a hash table in that namespace:

	sk_for_each(s, &net->unx.table.buckets[hash]) {
		// ...
	}

Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---

Notes:
    Verified in code

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

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index c370b021589a..762bf0d1fe08 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -257,7 +257,17 @@ .SS Abstract sockets
 Abstract sockets automatically disappear when all open references
 to the socket are closed.
 .P
-The abstract socket namespace is a nonportable Linux extension.
+A socket can connect or send to an abstract address
+only if the socket bound to that address
+is in the same network namespace
+(see
+.BR network_namespaces (7)).
+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
+Abstract sockets are a nonportable Linux extension.
 .\"
 .SS Socket options
 For historical reasons, these socket options are specified with a
-- 
2.56.0

[PATCH v2 5/6] man/man2/bind.2: ERRORS: EACCES: Write permission on the directory is required

[Günther Noack]

In addition to the search permission, binding a pathname 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).

Fixes: 9d1fd1157306 (1999-06-15, 2022-12-19; "man-pages 1.24")
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
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 @@ .SH ERRORS
 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 v2 6/6] 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.

	This is not something that the remote end normally does,
	but it's a possible corner case.

Cc: Kuniyuki Iwashima <kuniyu@google.com>
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 | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 762bf0d1fe08..2163a91514b9 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -645,9 +645,24 @@ .SS Ioctls
 .\" and it may well change, probably best not to document this now.
 .SH ERRORS
 .TP
+.B EACCES
+Write permission is denied 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.
+The specified local address is already in use
+or the file 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
@@ -684,6 +699,11 @@ .SH ERRORS
 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
@@ -695,6 +715,11 @@ .SH ERRORS
 .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
@@ -706,6 +731,13 @@ .SH ERRORS
 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