SD_BUS_ENQUEUE_FOR_READ(3)

💅 SD_BUS_ENQUEUE_FOR_READ(3) — like, the manual page bestie 💅

okay so this is the page for sd_bus_enqueue_for_read, out of the sd_bus_enqueue_for_read section of the systemd manuals (yes the header's a whole thing, we're not doing that, we're doing vibes). sit down, grab a matcha, let's get into it 🍓

---

✨ NAME ✨

sd_bus_enqueue_for_read — the way you put a bus message back on a bus connection's queue so it can be read again. it's giving rewind, not restart 💫

---

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_enqueue_for_read(sd_bus *bus, sd_bus_message *message);

two args, no drama. she's simple like that 🎀

---

✨ DESCRIPTION ✨

so sd_bus_enqueue_for_read() is literally the "put it back, we're not done with it" function. it re-enqueues an incoming bus message onto the local read queue, so it gets processed and dispatched locally all over again — exactly like how a fresh incoming message from the peer gets handled. same energy, second time around 🔁

it takes a bus connection object and the message you want to enqueue. a reference is taken of the message, which means the caller's own reference stays right where it belongs — with the caller. no stealing, we're polite 🫶

and the message goes to the end of the queue bestie, so it gets dispatched after everything that was already queued. no cutting the line, no main character behavior in the queue 💅

now the important part, the actual use case: this call is primarily for incoming method calls that can only be processed after some other asynchronous operation finishes. the iconic example is PolicyKit authorization — when a newly incoming method call needs authorization, and then the PolicyKit response finally comes back, you can re-enqueue that original method call and process it again, this time with the authorization result known. chef's kiss, ate, no notes 👑

---

✨ RETURN VALUE ✨

• on success: she returns 0 or a positive integer 💚
• on failure: negative errno-style error code, as is tradition 😭

Errors

the errors she might throw your way:

• -ECHILD — the bus connection was created in a different process, library or module instance. different universe, can't touch this 🙈

---

✨ 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. link her up 🔗

all functions listed here are thread-agnostic, and only a single thread may operate on a given object at any given time. different threads can access the same object at different times. multiple independent objects? those can absolutely be used from different threads in parallel. sharing is fine, just not at the same time, iykyk 🌸

⚠️ the code described here uses getenv(3), which is declared to be not multi-thread-safe. so if you're calling the functions described here, do not call setenv(3) from a parallel thread. the recommendation is to only do setenv() calls from an early phase of the program — before any other threads have been started. like, get it done first, then start the party 🎉

---

✨ HISTORY ✨

sd_bus_enqueue_for_read() was added in version 245. a classic, an icon, we stan ⭐

---

✨ SEE ALSO ✨

• systemd(1)
• sd-bus(3)
• sd_bus_send(3)

---

and that's the whole page bestie, no cap 💖 this one's from systemd 261.3, page SD_BUS_ENQUEUE_FOR_READ(3) — go forth and re-enqueue responsibly, love u, bye 🦋🌈👑