SD_VARLINK_SEND(3)

💌 SD_VARLINK_SEND — the sd_varlink_send girlies 💅

okay bestie, so this page is literally about sd_varlink_send, sd_varlink_sendb, and sd_varlink_sendbo — three functions that enqueue a Varlink method call and then just… don't wait around for a reply. main character energy, no follow-up texts. 🦋

---

✨ NAME ✨

sd_varlink_send, sd_varlink_sendb, sd_varlink_sendbo — enqueues a Varlink method call, and no, she is not expecting a reply 💀

---

🌸 SYNOPSIS 🌸

#include <systemd/sd-varlink.h>

int sd_varlink_send(sd_varlink *link, const char *method,
                    sd_json_variant *parameters);

int sd_varlink_sendb(sd_varlink *link, const char *method, ...);

int sd_varlink_sendbo(sd_varlink *link, const char *method, ...);

---

💖 DESCRIPTION 💖

so sd_varlink_send() submits a method call over a Varlink connection, periodt. you hand it the Varlink connection object, a method name as a string parameter, and a JSON object stuffed with the parameters you wanna pass — all as function parameters. and here's the tea: this call is asynchronous, meaning the message is not delivered right away. it only goes out once sd_varlink_process(3) gets invoked. (which, lowkey, happens automatically in one of the following event loop iterations — but only if the Varlink connection is attached to an event loop. iykyk.)

sd_varlink_sendb() is giving the same energy as sd_varlink_send(), except instead of you showing up with a fully constructed sd_json_variant object carrying the parameters, that object gets constructed on-the-fly, directly from the parameter list — in a style identical to sd_json_build(3). ✨

sd_varlink_sendbo() is literally identical to sd_varlink_sendb(), but an enclosing object is implicitly added, so the parameter list is expected to consist of field pairs only. for the full deets on the expected argument list, go look at sd_json_buildo(3). 🎀

bestie, listen. use sd_varlink_send(), sd_varlink_sendb() and sd_varlink_sendbo() only if you don't need any method call results, because they provide neither return parameters nor success/failure information. like, zero. nada. if you actually want the server's response, use sd_varlink_call(3) (and related calls) to submit a method call synchronously. 👑

---

⭐ RETURN VALUE ⭐

on success, sd_varlink_send(), sd_varlink_sendb() and sd_varlink_sendbo() return a non-negative integer. slay. on failure, they return a negative errno-style error code. 😭

🙈 Errors

the errors they might throw at you indicate the following problems:

• -EINVAL — an argument is invalid. girl, check ur args.
• -ENOMEM — memory allocation failed. the malloc said no 💀
• -ENOTCONN — the Varlink connection object is not connected. she's not even online rn.
• -EBUSY — the Varlink connection object is already used for other purposes, i.e. executing a method call or similar. she's booked and busy, one thing at a time bestie 🎀
• -ENOBUFS — the internal limit of queued messages for the Varlink connection has been reached. and okay, this limit is set very high, so hitting it typically indicates that the Varlink connection object is stalled — possibly because sd_varlink_process() has not been called regularly enough, or because the peer is not processing any queued messages. this limit is a safety precaution to ensure a stalled peer will not result in unbounded memory allocations on the client side. so like… it's a guardrail, not a vibe. 🛑

---

🧚 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. this means the code calling the functions described here must not call setenv(3) from a parallel thread. it is recommended to only do calls to setenv() from an early phase of the program, when no other threads have been started. no cap, just do it early and avoid the chaos. 🌈

---

👑 HISTORY 👑

sd_varlink_send(), sd_varlink_sendb(), sd_varlink_sendbo() were added in version 257. iconic behavior, honestly. 💜

---

🔥 SEE ALSO 🔥

systemd(1), sd-varlink(3), sd_varlink_call(3), sd_varlink_build(3)

---

and that's the whole page bestie!! 🎀✨ this little writeup is serving systemd 262.1, mwah, go forth and enqueue ur method calls 💖🦋