SD_BUS_PROCESS(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_PROCESS(3) — bestie, let's drive this connection

okay so this is the sd_bus_process page from section 3 of the manual, and honestly it's kind of the main character of sd-bus. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

sd_bus_process — literally just drive the connection, that's the whole vibe 🚗💨

🌸 SYNOPSIS 🌸

#include <systemd/sd-bus.h>

int sd_bus_process(sd_bus *bus, sd_bus_message **ret);

like, that's it. two params. iconic.

🦋 DESCRIPTION 🦋

okay so sd_bus_process() is the function that drives the connection between the client and the message bus. that's the whole job. it handles connecting, authentication, and processing of messages — the full backstage pass, no cap 💅

when you invoke it, pending I/O work gets executed, and queued incoming messages get dispatched to the registered callbacks. each time you invoke it, a single operation is executed. one. singular. one operation per call, bestie, it's not doing overtime.

it returns zero when no operations were pending, and positive if a message was processed. when zero comes back, that's your cue: the caller should poll for I/O events before calling into sd_bus_process() again. and for that you've got two options, pick your fighter:

sd_bus_process() processes at most one incoming message per call. okay so about that ret param:

  • if ret is not NULL and the call processed a message, *ret is set to this message. the caller owns a reference to this message and should call sd_bus_message_unref(3) when the message is no longer needed. don't ghost it, unref it 🫶
  • if ret is not NULL and progress was made, but no message was processed, *ret is set to NULL.

and here's the tea ☕ — only messages not already handled by the various types of registered message handlers get returned through this parameter. and those handlers are:

also note (fr fr, this one matters): if such a message handler returns a zero return value (as opposed to some value > 0), an incoming message will not be considered handled, and gets passed to other suitable handlers — until one returns > 0 — or returned by sd_bus_process() in case none of them returns > 0. it's giving "keep passing the aux until someone actually plays a song" 🎶

if the bus object is connected to an sd-event(3) event loop (with sd_bus_attach_event(3)), then you don't need to call sd_bus_process() directly — it gets invoked automatically when necessary. the event loop handles it, main character energy, you can just chill ✨

💖 RETURN VALUE 💖

  • positive integer — progress was made 🎉
  • 0 — no progress was made
  • negative errno-style error code — an error occurred 😭

🙈 Errors

returned errors may indicate the following problems, so let's do a vibe check on each:

  • -EINVAL — an invalid bus object was passed. wrong bus, bestie 💀
  • -ECHILD — the bus connection was allocated in a parent process and is being reused in a child process after fork(). that's a whole custody situation ngl
  • -ENOTCONN — the bus connection has been terminated already. it's over, it's done, it left the group chat
  • -ECONNRESET — the bus connection has been terminated just now. like, literally just now, fresh off the break-up 😭
  • -EBUSY — this function is already being called, i.e. sd_bus_process() has been called from a callback function that itself was called by sd_bus_process(). recursive queen behavior that we simply do not stan 🚫

🌈 NOTES 🌈

the functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file.

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. multiple independent objects may be used from different threads in parallel. so like, share the object across time, not across threads at the same moment. periodt 💅

⚠️ 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's recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. do it early, do it once, do it before the party starts 🎀

⭐ HISTORY ⭐

sd_bus_process() was added in version 221. a true elder of the sd-bus universe 👑

🔥 SEE ALSO 🔥

systemd(1), sd-bus(3), sd_bus_wait(3), sd_bus_get_fd(3), sd_bus_message_unref(3), sd-event(3), sd_bus_attach_event(3)

and that's the page!! 🦋 mwah, go forth and process exactly one (1) message per call, bestie. this cutie is documented in systemd 261.3, section 3 💖✨🎀

📦 where this page comes from