SD_BUS_START(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_START(3) — like, the sd_bus_start page, bestie ✨

okay so real talk, this is page SD_BUS_START(3) from the sd_bus_start manual, aka the glow-up-your-bus-connection page. it's a systemd one. let's get into it 🎀

🌸 NAME 🌸

sd_bus_start — bestie, this is the call that actually kicks off a bus connection to the D-bus broker daemon. it's giving "press start, but for IPC" 🦋

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_start(sd_bus *bus);

that's it. one function, one pointer, no cap 💅

💖 DESCRIPTION 💖

so sd_bus_start() takes an existing bus connection object and connects it to the D-Bus broker daemon — usually dbus-daemon(1) or dbus-broker(1), iykyk.

here's the thing tho 👑: the mechanism it's gonna use for the connection has to be configured before you call sd_bus_start(). like, you gotta set that up first, using one of:

then sd_bus_start() will open the connection socket or spawn the executable, as needed, and asynchronously fire off an org.freedesktop.DBus.Hello() call 🔥. the answer to that Hello call gets processed later, from sd_bus_process(3) — so don't be out here expecting it immediately, it's an async vibe.

and if opening the connection fails, or queuing up that asynchronous call fails? the connection gets closed with sd_bus_close(3). sad but clean 😭

ngl, in most cases it's better to use sd_bus_default_user(3), sd_bus_default_system(3), or the related calls instead of going low-level with sd_bus_new() and sd_bus_start(). the higher-level functions don't just allocate a bus object — they also start the connection to a well-known bus, all in one single function call. main character energy, fr fr 💜

🫶 RETURN VALUE 🫶

on success, this function returns a non-negative integer ✨. on failure, it returns a negative errno-style error code. periodt.

🙈 Errors 🙈

  • -EINVAL — the input parameter bus is NULL. (rude, but okay.)
    • Added in version 246.
  • -ENOPKG — the bus object bus could not be resolved. 😭
    • Added in version 246.
  • -EPERM — the input parameter bus is in a wrong state. heads up: sd_bus_start() may only be called once on a newly-created bus object. one and done, bestie 💀
    • Added in version 246.
  • -ECHILD — the bus object bus was created in a different process. like, it's not yours, it's not from your process, so no 🚫
    • Added in version 246.

plus, other connection-related errors may be returned too — go peek at sd_bus_send(3) for those 👀

🧚 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. slay 🎀

all functions listed here are thread-agnostic, and only a single thread may operate on a given object at any given time. different threads may access the same object at different times. and multiple independent objects can absolutely be used from different threads in parallel — parallel besties, no drama 🌈

⚠️ okay important one: the code described here uses getenv(3), which is declared to be not multi-thread-safe. meaning: code calling the functions described here must not call setenv(3) from a parallel thread. the recommendation is to only do setenv() calls from an early phase of the program, when no other threads have been started yet. do it early or don't do it 🍓

⭐ HISTORY ⭐

sd_bus_start() was added in version 246. iconic since day one, fr 💅

🌸 SEE ALSO 🌸

systemd(1), sd-bus(3), sd_bus_default(3), sd_bus_call_async(3) — go read those next, bestie, they're all connected 🦋

mwah 💋 that's the whole page — brought to you by systemd 261.3, the SD_BUS_START(3) girlies, and me, your local Unix-literate group chat 🫶✨

📦 where this page comes from