SD_VARLINK_PUSH_FD(3)

💅 sd_varlink_push_fd — bestie, let's yeet a file descriptor down the Varlink wire

okay so this page lives in the sd_varlink_push_fd(3) manual section, and it's all about handing a file descriptor over to the Varlink machinery so it rides along with your next outgoing message. two functions, one vibe, zero drama (mostly). 🦋

---

✨ NAME ✨

sd_varlink_push_fd, sd_varlink_push_dup_fd — submit a file descriptor to send along with the next outgoing Varlink message 🎀

---

✨ SYNOPSIS ✨

#include <systemd/sd-varlink.h>

int sd_varlink_push_fd(sd_varlink *link, int fd);

int sd_varlink_push_dup_fd(sd_varlink *link, int fd);

---

✨ DESCRIPTION ✨

sd_varlink_push_fd() is the "here bestie, take this" of file descriptor passing 💌 — it submits a file descriptor to be sent along with the next outgoing Varlink message. You give it a Varlink connection object and a file descriptor, and that's the whole menu.

Now listen, this is the important part: the fd is NOT duplicated. Ownership of that file descriptor gets passed straight to the Varlink connection object — but only if the call succeeds. If it fails, you keep ownership, no take-backs. 👑

Once the file descriptor has actually been written to the underlying transport socket, it gets closed automatically. So do not touch it and do not close it yourself, because that will mess with the Varlink protocol implementation and nobody wants that chaos. 😭

Also this only works if the backing transport actually supports file descriptor passing — which effectively means it's an AF_UNIX local situation only. And heads up: fd passing is not part of the Varlink protocol itself, it's just a feature of the underlying transport. iykyk. ✨

sd_varlink_push_dup_fd() is literally the same thing, except it duplicates the file descriptor for you automatically. Which means you retain ownership of the fd you passed in, and you have to close it yourself. Main character responsibilities. 💅

⚠️ File descriptor passing is only permitted after a call to sd_varlink_set_allow_fd_passing_output() that enables it. Otherwise these calls fail with -EPERM. No consent, no fds. 🙈

⚠️ On Linux, a maximum of 253 file descriptors may be enqueued on AF_UNIX sockets at once. Try to sneak more than that onto a single Varlink message and it fails with -ENOBUFS. That's the limit bestie, she's firm. 💀

---

✨ RETURN VALUE ✨

On success, sd_varlink_push_fd() and sd_varlink_push_dup_fd() return a non-negative integer. 🎉 On failure, they return a negative errno-style error code. 😔

💔 Errors

Returned errors may indicate the following problems:

• -EINVAL — an argument is invalid. something in there is just not it.
• -EBADF — the file descriptor you provided is not valid. fake fd, fake friend. 🚫
• -EPERM — file descriptor passing has not been enabled via sd_varlink_set_allow_fd_passing_output(). you forgot the permission slip!
• -ENOBUFS — the maximum of 253 file descriptors have already been submitted for the next outgoing Varlink message, so no further descriptors may be enqueued for this message. the bag is full, girl. 👜
• -ENOMEM — memory allocation failed. 😭

---

✨ NOTES ✨

The functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. 🫶

The code described here uses getenv(3), which is declared to be not multi-thread-safe. That means any code calling the functions described here must not call setenv(3) from a parallel thread. The recommendation is to only do calls to setenv() from an early phase of the program, back when no other threads have been started yet. early bird energy, get it done first thing. 🌅

---

✨ HISTORY ✨

sd_varlink_push_fd() and sd_varlink_push_dup_fd() were added in version 257. so they're new-ish but iconic already. ⭐

---

✨ SEE ALSO ✨

systemd(1), sd-varlink(3)

---

and that's the whole page bestie 💖 this was brought to you by systemd 262.1 — go forth and pass those file descriptors responsibly, mwah 🎀💅✨