add utils for passing file descriptor between processes by echoechoin · Pull Request #4019 · util-linux/util-linux

echoechoin · 2026-02-04T06:59:40Z

Based on the outcomes of Discussion #3683, I have developed this demo, with the relevant operation example as follows:

 ~/util-linux # ./build/fdrecv -f 0 test --run cat &
[1] 1200890
 ~/util-linux # echo "hello world" | ./build/fdsend -f 0 test
hello world
[1]  + 1200890 done       ./build/fdrecv -f 0 test --run cat

masatake · 2026-02-04T07:42:21Z

+		}
+
+		/* get fd_to_send by open /proc/PID/fd/FD */
+		fd_to_send = open(proc_path, O_RDWR);


open(2) works for an fd opening a regular file.
For fds opening peculiar objects like sockets, we can use pidfd_getfd as a fallback.

How about using pidfd_getfd at first, then fall back to open if errno == ENOSYS || errno == EPERM.

The semantics of calling open(/proc/$pid/fd/$fd) and of calling pidfd_getfd($fd) differ.
open makes a new open file object in the kernel.
pidfd_getfd doesn't. pidfd_getfd makes a new reference to the open file.

If a receiver process calls lseek on a received file descriptor, it affects on the open file behind the fd.

open(2)

[target process]<fd> ------ [file object] --- [dentry] --- [inode] / [receiver process]<fd> -----[file object] --/

pidfd_getfd(2)

[target process]<fd> ------ [file object] --- [dentry] --- [inode] / [receiver process]<fd> ----/

I would like to withdraw my comment.

I think users expect the behavior of open(2). So, using the open(2) method is better as the default method.

What about activating the pidfd_getfd(2) method only if --pidfd-getfd option is given?

Now I believe it is better to activate the pidfd_getfd(2) method only if --pidfd-getfd option is given. No fallback.

masatake · 2026-02-04T07:47:05Z

It seems you need to add bash-completion files for your new commands.

cgoesche · 2026-02-04T15:50:28Z

+			opt_pid = strtopid_or_err(optarg, _("invalid pid"));
+			if (opt_pid < 1)
+				errx(EXIT_FAILURE, _("pid must be positive"));


You can also use this internal lib function. It would make way for a potential PID:inode support which could be interesting for fd{recv,send}, since it'll help avoid sending/receiving a fd from/to a wrong process (in cases where that is important of course).

Suggested change

opt_pid = strtopid_or_err(optarg, _("invalid pid"));

if (opt_pid < 1)

errx(EXIT_FAILURE, _("pid must be positive"));

opt_pid = ul_parse_pid_str_or_err(optarg, &opt_pid, NULL);

For some context in regards to PID:inode: #3953 (comment)

masatake · 2026-02-04T19:50:52Z

What about extending fdrecv to receive multiple fds?
We can add the implementation later, but we must design the CLI now in case.

echoechoin · 2026-02-05T04:15:47Z

What about extending fdrecv to receive multiple fds? We can add the implementation later, but we must design the CLI now in case.

How about this:

# Send multiple fds:
fdsend --block --fd 0,1,2 -b pipe_test

# Receive multiple fds:
fdrecv --fd 0,1,2 pipe_test --run cat  # 0 <-> 0, 1 <-> 1, 2 <-> 2 (full mapping)
fdrecv --fd 0,1   pipe_test --run cat  # 0 <-> 0, 1 <-> 1 (2 is ignored)
fdrecv --fd 0     pipe_test --run cat  # 0 <-> 0 (1 and 2 are ignored)

Also ensure that --fd, --stdin, --stdout, and --stderr are mutually exclusive,
and --stdin, --stdout, and --stderr accepting only the first single fd.

# Send multiple fds:
fdsend --block --fd 0,1,2 -b pipe_test

# Receive only first fd via --stdin, --stdout, or --stderr:
fdrecv --stdin pipe_test --run cat # 0 <-> stdin, ignore other fds.

masatake · 2026-02-07T21:33:39Z

What about supporting an abstract Unix socket (https://man7.org/linux/man-pages/man7/unix.7.html)?
It may help users pass a file descriptor between processes in different mount namespaces.

echoechoin · 2026-02-09T01:44:22Z

What about supporting an abstract Unix socket (https://man7.org/linux/man-pages/man7/unix.7.html)? It may help users pass a file descriptor between processes in different mount namespaces.

How about add a new command option for abstract unix socket?

fdsend --abstract --fd 1 sockspec
fdrecv --abstract --fd 1 sockspec run cat

or add an @ sign before sockspec to indicate it is a abstract unix socket:

fdsend --fd 1 @sockspec
fdrecv --fd 1 @sockspec run cat

masatake · 2026-02-09T07:42:27Z

Adding --abstract looks better for me.

Rationals:

--abstract option requires more type than @socket. It implies that passing an fd via an abstract socket requires care.

For abstract sockets, we cannot use inotify to detect the appearance of a listening socket. So the usability of these commands with --abstract differs from the commands without the option.

--abstract option allows users passing an fd via /run/user/$UID/fdsend/@fname :-)

echoechoin · 2026-02-09T08:12:39Z

In abstract and blocking mode, may be we can retry on ECONNREFUSED at intervals (like 500ms) until connect succeed, then send the file descriptor. Or other approaches?

masatake · 2026-02-09T18:07:04Z

I don't have any other idea than the polling approach.
For implementing private tools, watching the unix_bind() invocation with BPF can be a choice. However, I think it is not suitable for a tool in util-linux.

+ * Receiver: socket/bind/listen/accept, recvmsg with SCM_RIGHTS.
+ * On success sets *out_fd to the received fd and returns 0.
+ */
+static int fdrecv_accept_and_recv_fd(const char *sockpath, int *out_fd, int abstract)


cgoesche · 2026-02-12T02:53:08Z

+	FILE *out = stdout;
+
+	fputs(USAGE_HEADER, out);
+	fprintf(out, _(" %s [options] SOCKSPEC --run command args...\n"), program_invocation_short_name);


I find that --run is a bit unnecessary. Since SOCKSPEC can not be specified an arbitrary amount of time, we can simply design the CLI like this:

fdrecv [options] SOCKSPEC COMMAND

COMMAND will have an arbitrary amount of arguments, which is fine as these will be the remaining elements of argv and we'll just pass them to execvp(2).

What do you think ?

#4019 (comment)

If we extend fdrecv to accept fds from multiple sockets, the fdcecv command line can become complicated. In these cases, the --run option helps people understand the command line.

If the action that fdrecv takes after receiving all fds is only "run", we can choose -- (or -) instead of --run.

masatake · 2026-02-16T21:08:32Z

It would be nice if fdrecv could receive multiple fds from different sockets at once.
This is just an idea.

terminal A

fdsend --fd 0 sockA

terminal B

fdsend --pid 9999 --fd 1 sockB

terminal C

fdsend --pid 9999 --fd 32 sockC

trminal recv:

fdrecv -f 3 sockA -f 2 sockB -f 0 sockC --run CMD

This commit implements the fdsend and fdrecv utilities as proposed in Discussion util-linux#3683. It adds: - fdsend: send a file descriptor to a Unix domain socket (path-based). Supports blocking wait for receiver, optional pid/fd resolution, and pidfd_getfd(2) where available. - fdrecv: receive a file descriptor from a Unix domain socket and optionally exec a program with the received fd. Signed-off-by: WanBingjiang <wanbingjiang@webray.com.cn>