SD_BUS_CLOSE(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 sd_bus_close(3) — the sd_bus_close manual, bestie edition 🎀

okay so this is the sd_bus_close(3) page, and it's basically the "how to say goodbye to your D-Bus connection without losing messages" saga. grab a strawberry drink 🍓 and let's get into it.

✨ NAME ✨

sd_bus_close, sd_bus_flush, sd_bus_default_flush_close — close and flush a bus connection. that's the whole vibe: shutting things down cleanly. 💅

🦋 SYNOPSIS 🦋

#include <systemd/sd-bus.h>

void sd_bus_close(sd_bus *bus);

int sd_bus_flush(sd_bus *bus);

void sd_bus_default_flush_close(void);

like, look at those signatures. void in, void out, and one little int in the middle that's gonna tell you if things went off. 👑

🌸 DESCRIPTION 🌸

sd_bus_close() — the actual breakup 💔

sd_bus_close() disconnects the specified bus connection. and bestie, when this call is invoked and the specified bus object refers to an active connection, it is immediately terminated. like, no negotiation, no "let's talk about it", it's done.

no further messages may be sent or received on it. periodt.

any messages queued in the bus object — both incoming and outgoing — are released. gone. released into the void. 🫶

but here's the thing: if you invoke it on a NULL bus object, or when the bus connection is already closed, this function executes no operation. it's chill like that. no crash, no drama.

and the big one, the thing everyone gets wrong: this call does not free or unreference the bus object itself. it does not. use sd_bus_unref(3) for that. don't @ me, that's just how it is. 😭

sd_bus_flush() — the "wait, I still have things to say" 😤

sd_bus_flush() synchronously writes out all outgoing queued messages on a bus connection, if there are any. that's it. that's the job.

⚠️ heads up: this function call may block if the peer is not processing bus messages quickly. so if the other side is being slow, you're just gonna sit there. lowkey the price of doing business.

the exit ritual 🕯️

before a program exits it is usually a good idea to flush any pending messages with sd_bus_flush() and then close connections with sd_bus_close() — this ensures that:

  • no unwritten messages are lost 💌
  • no further messages may be queued 🚫
  • all incoming but unprocessed messages are released 🗑️

after both operations have been done, it is a good idea to also drop any remaining references to the bus object so that it may be freed. three steps, one vibe.

and because these three operations are frequently done together, a helper call sd_bus_flush_close_unref(3) is provided that combines them into one. iconic. ate. no notes. 🔥

sd_bus_default_flush_close() — the group-chat cleanup 🧹

sd_bus_default_flush_close() is similar to sd_bus_flush_close_unref(), but it does not take a bus pointer argument. instead, it iterates over any of the "default" buses opened by:

it's particularly useful to clean up any buses opened using those calls before the program exits. like closing all your tabs at once. main character energy. ✨

⭐ RETURN VALUE ⭐

on success, sd_bus_flush() returns a non-negative integer. 🎉

on failure, it returns a negative errno-style error code. 💀

(also shouting out that sd_bus_close() and sd_bus_default_flush_close() return void, so they don't have a return value at all — it's giving "no thoughts, just vibes".)

🌈 Errors 🌈

returned errors may indicate the following problems:

  • -ECHILD — the bus connection has been created in a different process, library or module instance. 😬 so like, not your bus, not your business.

💜 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 nicely. 💅

⚠️ the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means that 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. fr fr, do your env stuff early and then leave it alone. 🙈

🎀 HISTORY 🎀

  • sd_bus_close() and sd_bus_flush() were added in version 221.
  • sd_bus_default_flush_close() was added in version 227.

glow-up timeline, honestly. ⭐

👑 SEE ALSO 👑

systemd(1), sd-bus(3), sd_bus_unref(3), sd_bus_set_close_on_exit(3)

okay that's the page!! go flush your messages and close your buses responsibly, bestie 💖 this was dropped by systemd 261.3, so if your build says something else, check your version — iykyk 🌸🦋

📦 where this page comes from