SD_BUS_SLOT_SET_FLOATING(3)

💖 NAME

sd_bus_slot_set_floating, sd_bus_slot_get_floating — control whether a bus slot object is “floating”. Hii bestie, welcome to the SD_BUS_SLOT_GET_FLOATING(3) page — it’s giving “two functions, one manual page” energy ✨.

🎀 SYNOPSIS

#include <systemd/sd-bus.h>

int sd_bus_slot_set_floating(sd_bus_slot *slot, int b);

int sd_bus_slot_get_floating(sd_bus_slot *slot);

🦋 DESCRIPTION

Okay so sd_bus_slot_set_floating() is the one that decides whether the specified bus slot object slot is “floating” or not. A floating bus slot object has its lifetime tied to the lifetime of the bus object it’s associated with: it stays allocated as long as the bus object itself does, and it gets freed automatically when the bus object is freed. Literally attached at the hip, no cap.

Regular (i.e. non-floating) bus slot objects keep the bus referenced, so the bus object stays allocated at least as long as at least one referenced bus slot object is still around. So the floating state flips the direction of referencing between the bus object and the bus slot objects: if it’s floating, the bus pins the bus slot; otherwise the bus slot pins the bus objects. Use sd_bus_slot_set_floating() to switch between both modes: if the b parameter is zero, the slot object is made into a regular (non-floating) slot object; otherwise it is made into a floating slot object. No in-between, bestie 💅.

Bus slot objects may be allocated with calls such as sd_bus_add_match(3). If the slot of these functions is non-NULL, the slot object will be of the regular kind (i.e. non-floating); otherwise it will be created floating. With sd_bus_slot_set_floating() a bus slot object allocated as regular can be converted into a floating object and back. This is particularly useful for creating a bus slot object, then changing parameters of it, and then turning it into a floating object, whose lifecycle is managed by the bus object. Main character move: build it, tweak it, hand over the keys 🔥.

sd_bus_slot_get_floating() returns the current floating state of the specified bus slot object. It returns negative on error, zero if the bus slot object is a regular (non-floating) object and positive otherwise.

🌈 RETURN VALUE

On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error code. That’s the whole vibe check 💅.

😭 Errors

Returned errors may indicate the following problems:

• -EINVAL — The slot parameter is NULL.
• -ECHILD — The bus connection has been created in a different process, library or module instance.
• -ESTALE — The bus object the specified bus slot object is associated with has already been freed, and hence no change in the floating state can be made anymore. Rip 😭.

🧚 NOTES

Functions described here are available as a shared library, which can be compiled against and linked 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. Multiple independent objects may be used from different threads in parallel.

⚠️ 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. This is not the vibe to freelance, bestie 🫶.

⭐ HISTORY

sd_bus_slot_set_floating() and sd_bus_slot_get_floating() were added in version 239. A little vintage, but still iconic 💜.

🫶 SEE ALSO

systemd(1), sd-bus(3), sd_bus_slot_set_destroy_callback(3), sd_bus_add_match(3)

---

okay bye bestie 💖 this page is from systemd 261.3; the footer tag is SD_BUS_SLOT_SET_FLOATING(3), and there’s no separate date in the footer to report. No cap ✨.