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

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

On Sat, Oct 24, 2026 at 05:22:56AM +0000, Kuniyuki Iwashima wrote:
> On Wed, 21 Oct 2026 23:22:55 +0200, Günther Noack wrote:
> > These were added in linux.git 5e2ff6704a27 (2023-06-12; "scm: add
> > SO_PASSPIDFD and SCM_PIDFD") and 7b26952a91cf (2023-06-12; "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 Linux 6.17, with c679d17d3f2d (2025-07-04; "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 Linux 6.16, with 20b70e58961b (2025-04-28; "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 67dd10cc146f..a4457508fd2a 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
> 
> Why does pidfd only have SHA1 ?

I'm removing it from the code and keeping it in the commit message, as
in the other commits above.


> > @@ -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.
> 
> Not sure if this is worth noting here, but "peer process" is
> a bit unclear.
> 
> For example, if process A creates socekt A, calls listen(),
> and pass it to process B and close()s the fd, and process C
> creates socket C and connects to socket A, then getsockopt(C,
> SO_PEERPIDFD) will return process A, not B.

I think it is OK; The phrase "peer process connected to this socket"
is adapted from the description of SO_PEERCRED, and to clarify, the
next sentence refers to the description of SO_PEERCRED in the same
file:

> > +This is the process whose credentials are returned by
> > +.BR SO_PEERCRED .

^ Here

I think the SO_PEERCRED description is good:

  This read-only socket option returns the credentials of the peer
  process connected to this socket.  The returned credentials are
  those that were in effect at the time of the call to connect(2),
  listen(2) or sockepair(2).

(It is good, because it puts the common use case first, where the
entire BSD socket dance is done by the same process, and then
clarifies the details for the people who need them.)

So this seems fair to me, imho.  Let me know whether that seems
acceptable to you.

–Günther