| SYD-FD(1) | General Commands Manual | SYD-FD(1) |
syd-fd - Interact with remote file descriptors
syd-fd [-h] [-p pid] [-f
remote_fd[:local_fd]]... {command [args...]}
syd-fd [-hw] -u socket [-m msg] [-f
fd[,fd...]]...
syd-fd utility can be used to interact with file descriptors on Linux systems. It operates in one of two modes: transferring remote file descriptors with pidfd_getfd(2), or sending file descriptors over a UNIX domain socket with SCM_RIGHTS.
In first mode, given only a PID argument with -p, it lists the open files of the process with the given PID in line-oriented compact JSON format. Given no PID argument it lists the open files of the current process. The -f argument can be used to transfer remote file descriptors using pidfd_getfd(2) which requires Linux>=5.6. Optionally a local file descriptor to use as the target may be appended after a colon. Specify "rand" as target to duplicate the file descriptor to a random available file descriptor slot. If a command is given it is executed and the file descriptors are transferred to the process. If no command is given "/bin/sh" is executed.
In second mode, selected with -u, it connects to the given UNIX domain socket and sends a single message carrying the file descriptors given with -f as SCM_RIGHTS ancillary data of unix(7). A leading @ in the socket address denotes an abstract UNIX socket. The -f arguments are local file descriptor numbers: caller is supposed to open them, e.g. with shell redirections. Message line may be given with -m and defaults to empty. Both -m and -f are optional, so the mode may also be used to send plain messages without file descriptors. Any limit on the number of descriptors per message is the receiver's policy: syd(2) IPC socket accepts exactly one configuration file descriptor per message. By default syd-fd exits right after the send without waiting for a response, given -w it waits for a response regardless of what was sent, and prints it to standard output until peer closes the connection. Above all, this mode is useful to load sandbox configuration over the syd(2) IPC socket. A received file descriptor constitutes the load request, and the message carrying it must consist of the sole command "load".
| -h | Display help. |
| -p pid | Specify process ID. If not given, list fds of current process. |
| -f remote_fd[:local_fd] | Specify remote fd to transfer. A local target fd may be appended after a colon, or "rand" for a random target. |
| -u socket | Connect to the UNIX domain socket and send the given fds with SCM_RIGHTS. A leading @ denotes an abstract socket. The fds to send are given with -f, repeated or comma-separated. |
| -m line | Specify the message line to send with -u. Optional, defaults to empty. |
| -w | Wait for a response with -u, regardless of what was sent, and print it to standard output. By default syd-fd exits right after the send. |
syd-fd exits with the same exit code as the command. With -u, it exits 0 on success, and with the errno(3) of the failed system call on failure.
Load sandbox configuration over syd(2) IPC socket:
$ syd-fd -w -u @sandbox.sock -m load -f 3 3<paludis.syd-3
{"err":0,"msg":"ACK"}
syd(1), syd(2), syd(5), syd-lock(1), syd-pds(1), pidfd_getfd(1), unix(7)
syd homepage: https://sydbox.exherbo.org/
Maintained by Ali Polatel. Up-to-date sources can be found at https://gitlab.exherbo.org/sydbox/sydbox.git and on Radicle at rad:z38HCnbmcDegA2BMxuPaPRPMdp6wF. Bugs/patches can be submitted to https://gitlab.exherbo.org/groups/sydbox/-/issues. Discuss in #sydbox on Libera Chat or in #sydbox:mailstation.de on Matrix.
| 2026-07-12 |