SYD-FD(1)

💅 SYD-FD(1) — the remote file descriptor whisperer

okay bestie, so this is syd-fd, chillin' in the General Commands Manual section, and it's literally about interacting with remote file descriptors. yes. file descriptors. from afar. it's giving long-distance relationship but make it syscalls 🦋

---

✨ SYNOPSIS ✨

syd-fd [-h] [-p pid] [-f remote_fd[:local_fd]]... {command [args...]}
syd-fd [-hw] -u socket [-m msg] [-f fd[,fd...]]...

two whole moods, two whole lines. pick your fighter 💅

---

🌸 DESCRIPTION 🌸

so syd-fd is the utility you use to interact with file descriptors on Linux systems, and ngl it's got two modes, like a dual-threat icon. 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. both slay, just differently ✨

💖 mode one: the remote fd heist

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. yes, JSON. we love a machine-readable moment 🎀

given no PID argument, it lists the open files of the current process. lowkey convenient.

the -f argument can be used to transfer remote file descriptors using pidfd_getfd(2) which requires Linux>=5.6. bestie, check your kernel, i'm serious 😭

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 — chaotic? maybe. iconic? absolutely 🔥

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. no thoughts, just shell 🫶

🦋 mode two: the socket send

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). fancy. we love ancillary data 💅

a leading @ in the socket address denotes an abstract UNIX socket. important detail, don't forget it ✨

the -f arguments are local file descriptor numbers: caller is supposed to open them, e.g. with shell redirections. you're the main character here, you do the opening 👑

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. sometimes a girl just wants to send a text, no attachments 💌

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. one. uno. don't push it 🙈

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. patient queen behavior 🌸

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". that's the whole vibe check — anything else and it's not loading, periodt 💀

---

👑 OPTIONS 👑

• -h — Display help. the "help me help you" of flags 🫶
• -p pid — Specify process ID. If not given, list fds of current process. (yes, your own. self-care 💅)
• -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. goblin mode fd allocation ✨
• -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. so many ways to hand over your fds 🎀
• -m line — Specify the message line to send with -u. Optional, defaults to empty. it's giving "k" text 💀
• -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. the "wait, come back" flag 😭

---

🔥 EXIT STATUS 🔥

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. so if it flops, it tells you exactly how it flopped. transparent queen 🌈

---

⭐ EXAMPLES ⭐

load sandbox configuration over syd(2) IPC socket — this is the moment, the whole reason you're here:

$ syd-fd -w -u @sandbox.sock -m load -f 3 3<paludis.syd-3
{"err":0,"msg":"ACK"}

look at that ACK. immaculate. no notes 👑

---

🌟 SEE ALSO 🌟

syd(1), syd(2), syd(5), syd-lock(1), syd-pds(1), pidfd_getfd(1), unix(7)

syd homepage: https://sydbox.exherbo.org/ — go read it bestie, it's free lore 🦋

---

💜 AUTHORS 💜

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. come hang out, the group chat is open 🫶💬

---

and that's the whole page, bestie!! this one's dated 2026-09-01, SYD-FD(1) in the General Commands Manual, and it ate. go transfer some file descriptors responsibly 💅✨🎀