SD-VARLINK(3)

💅 SD-VARLINK(3) — like, the whole sd-varlink manual page, bestie ✨

okay so welcome to sd-varlink (section 3 of the manual, if we're being official about it) — literally the whole glow-up guide to Varlink IPC, and I'm gonna walk you through every single bit of it 🫶

---

🌸 NAME 🌸

sd-varlink — APIs for Varlink IPC. that's it, that's the name, and it ate 💅

---

✨ SYNOPSIS ✨

#include <systemd/sd-varlink.h>

pkg-config --cflags --libs libsystemd

like yes, those two lines, copy them, love them, put them in your build 🎀

---

🦋 DESCRIPTION 🦋

so sd-varlink.h is part of libsystemd(3) and it's the header that gives you APIs for implementing Varlink IPC clients and services. both!! versatile icon behavior 👑

if you wanna know more about Varlink IPC itself, the link is https://varlink.org/ — go read, it's giving documentation excellence 🌈

Varlink IPC uses JSON[1] as its marshalling format. and the sd-varlink API relies on the sd-json(3) API for all the JSON serialization, deserialization and manipulation. so it's not doing JSON alone, it's got backup 💜

🎀 Canonical encoding rules 🎀

okay this part is lowkey important so pay attention bestie:

sd-varlink omits the "parameters" member on the wire in replies, errors, and notifications when there are no parameters to transmit. why? because it reduces message size and avoids ambiguity — efficiency slay ✨

receivers must be tolerant and accept any of the following encodings for the absence of parameters:

• an omitted "parameters" key — this one is the preferred vibe 💖
• a JSON null value
• an empty object {}

and when decoding, sd-varlink treats JSON null as if the member was omitted. no cap, it just handles it 🙈

also the varlinkctl(1) tool makes all the functionality implemented by sd-varlink available from the command line, so you can absolutely do this in your terminal, main character energy fr fr 🔥

---

😭 NOTES 😭

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

but here's the caveat so listen up: the code described here uses getenv(3), which is declared to be not multi-thread-safe. which means the 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, when no other threads have been started. like do it early or don't do it at all, periodt 🫶

bestie this is a real one — don't be out here calling setenv() from a parallel thread, that's the danger zone 💀

---

🧚 DIRECTORIES 🧚

• /usr/lib/systemd/varlink-bridges/ — okay so when sd_varlink_connect_url() encounters a URL with a scheme that is not natively supported, it goes looking in this directory for a bridge helper binary named after the URL scheme. the binary gets invoked the same way as exec: binaries, but with the full URL passed as the first command line argument. iconic delegation behavior 👑

for example: if varlinkctl introspect https://example.com/ws/sockets/io.systemd.Hostname is called, varlinkctl will look for an executable /usr/lib/systemd/varlink-bridges/https and invoke it with "https://example.com/ws/sockets/io.systemd.Hostname" as its only argument. like, that's exactly how it goes down, character for character 🍓

---

⭐ SEE ALSO ⭐

systemd(1), sd-event(3), sd-json(3), varlinkctl(1), sd-bus(3), pkg-config(1) — go read them, they're all in the friend group 💜

---

💖 NOTES 💖

1. JSON — https://json.org/ 🌸

---

and that's the whole page bestie, every flag, every path, every caveat, nothing skipped 💅 this was systemd 261.3, SD-VARLINK(3), and honestly? she ate. mwah 🎀✨🦋