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

[Kuniyuki Iwashima <kuniyu@google.com>]

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 ?


> +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.

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.


> +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
> @@ -543,6 +607,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,
> @@ -1273,6 +1373,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
>