1SD_BUS_SLOT_SET_FLOATING(3)sd_bus_slot_set_floatingSD_BUS_SLOT_SET_FLOATING(3)
2
3
4
6 sd_bus_slot_set_floating, sd_bus_slot_get_floating - Control whether a
7 bus slot object is "floating"
8
10 #include <systemd/sd-bus.h>
11
12 int sd_bus_slot_set_floating(sd_bus_slot *slot, int b);
13
14 int sd_bus_slot_get_floating(sd_bus_slot *slot);
15
17 sd_bus_slot_set_floating() controls whether the specified bus slot
18 object slot shall be "floating" or not. A floating bus slot object's
19 lifetime is bound to the lifetime of the bus object it is associated
20 with, meaning that it remains allocated as long as the bus object
21 itself and is freed automatically when the bus object is freed. Regular
22 (i.e. non-floating) bus slot objects keep the bus referenced, hence the
23 bus object remains allocated at least as long as there remains at least
24 one referenced bus slot object around. The floating state hence
25 controls the direction of referencing between the bus object and the
26 bus slot objects: if floating the bus pins the bus slot, and otherwise
27 the bus slot pins the bus objects. Use sd_bus_slot_set_floating() to
28 switch between both modes: if the b parameter is zero, the slot object
29 is considered floating, otherwise it is made a regular (non-floating)
30 slot object.
31
32 Bus slot objects may be allocated with calls such as
33 sd_bus_add_match(3). If the slot of these functions is non-NULL the
34 slot object will be of the regular kind (i.e. non-floating), otherwise
35 it will be created floating. With sd_bus_slot_set_floating() a bus slot
36 object allocated as regular can be converted into a floating object and
37 back. This is particularly useful for creating a bus slot object, then
38 changing parameters of it, and then turning it into a floating object,
39 whose lifecycle is managed by the bus object.
40
41 sd_bus_slot_get_floating() returns the current floating state of the
42 specified bus slot object. It returns negative on error, zero if the
43 bus slot object is a regular (non-floating) object and positive
44 otherwise.
45
47 On success, these functions return 0 or a positive integer. On failure,
48 they return a negative errno-style error code.
49
50 Errors
51 Returned errors may indicate the following problems:
52
53 -EINVAL
54 The slot parameter is NULL.
55
56 -ECHILD
57 The bus connection has been created in a different process, library
58 or module instance.
59
60 -ESTALE
61 The bus object the specified bus slot object is associated with has
62 already been freed, and hence no change in the floating state can
63 be made anymore.
64
66 Functions described here are available as a shared library, which can
67 be compiled against and linked to with the libsystemd pkg-config(1)
68 file.
69
70 The code described here uses getenv(3), which is declared to be not
71 multi-thread-safe. This means that the code calling the functions
72 described here must not call setenv(3) from a parallel thread. It is
73 recommended to only do calls to setenv() from an early phase of the
74 program when no other threads have been started.
75
77 systemd(1), sd-bus(3), sd_bus_slot_set_destroy_callback(3),
78 sd_bus_add_match(3)
79
80
81
82systemd 254 SD_BUS_SLOT_SET_FLOATING(3)