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

[Kuniyuki Iwashima <kuniyu@google.com>]

On Tue, 27 Oct 2026 00:02:04 +0100, Günther Noack wrote:
> 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.

Probably okay as is.  Maybe not many people is using socket
activation w/ systemd.