1SD_BUS_TRACK_NEW(3)            sd_bus_track_new            SD_BUS_TRACK_NEW(3)
2
3
4

NAME

6       sd_bus_track_new, sd_bus_track_ref, sd_bus_track_unref,
7       sd_bus_track_unrefp, sd_bus_track_set_recursive,
8       sd_bus_track_get_recursive, sd_bus_track_get_bus,
9       sd_bus_track_get_userdata, sd_bus_track_set_userdata - Track bus peers
10

SYNOPSIS

12       #include <systemd/sd-bus.h>
13
14       int sd_bus_track_new(sd_bus* bus, sd_bus_track** ret,
15                            sd_bus_track_handler_t handler, void* userdata);
16
17       sd_bus_track *sd_bus_track_ref(sd_bus_track *t);
18
19       sd_bus_track *sd_bus_track_unref(sd_bus_track *t);
20
21       void sd_bus_track_unrefp(sd_bus_track **t);
22
23       int sd_bus_track_get_recursive(sd_bus_track *t);
24
25       int sd_bus_track_set_recursive(sd_bus_track *t, int b);
26
27       sd_bus* sd_bus_track_get_bus(sd_bus_track *t);
28
29       void* sd_bus_track_get_userdata(sd_bus_track *t);
30
31       void* sd_bus_track_set_userdata(sd_bus_track *t, void *userdata);
32

DESCRIPTION

34       sd_bus_track_new() creates a new bus peer tracking object. The object
35       is allocated for the specified bus, and returned in the *ret parameter.
36       After use, the object should be freed again by dropping the acquired
37       reference with sd_bus_track_unref() (see below). A bus peer tracking
38       object may be used to keep track of peers on a specific IPC bus, for
39       cases where peers are making use of one or more local objects, in order
40       to control the lifecycle of the local objects and ensure they stay
41       around as long as the peers needing them are around, and unreferenced
42       (and possibly destroyed) as soon as all relevant peers have vanished.
43       Each bus peer tracking object may be used to track zero, one or more
44       peers add a time. References to specific bus peers are added via
45       sd_bus_track_add_name(3) or sd_bus_track_add_sender(). They may be
46       dropped again via sd_bus_track_remove_name() and
47       sd_bus_track_remove_sender(). Alternatively, references on peers are
48       removed automatically when they disconnect from the bus. If non-NULL
49       the handler may specify a function that is invoked whenever the last
50       reference is dropped, regardless whether the reference is dropped
51       explicitly via sd_bus_track_remove_name() or implicitly because the
52       peer disconnected from the bus. The final argument userdata may be used
53       to attach a generic user data pointer to the object. This pointer is
54       passed to the handler callback when it is invoked.
55
56       sd_bus_track_ref() creates a new reference to a bus peer tracking
57       object. This object will not be destroyed until sd_bus_track_unref()
58       has been called as many times plus once more. Once the reference count
59       has dropped to zero, the specified object cannot be used anymore,
60       further calls to sd_bus_track_ref() or sd_bus_track_unref() on the same
61       object are illegal.
62
63       sd_bus_track_unref() destroys a reference to a bus peer tracking
64       object.
65
66       sd_bus_track_unrefp() is similar to sd_bus_track_unref() but takes a
67       pointer to a pointer to an sd_bus_track object. This call is useful in
68       conjunction with GCC's and LLVM's Clean-up Variable Attribute[1]. Note
69       that this function is defined as inline function.
70
71       sd_bus_track_ref(), sd_bus_track_unref() and sd_bus_track_unrefp()
72       execute no operation if the passed in bus peer tracking object is NULL.
73
74       Bus peer tracking objects may exist in two modes: by default they
75       operate in non-recursive mode, but may optionally be switched into
76       recursive mode. If operating in the default non-recursive mode a peer
77       is either tracked or not tracked. In this mode invoking
78       sd_bus_track_add_name() multiple times in a row for the same peer is
79       fully equivalent to calling it just once, as the call adds the peer to
80       the set of tracked peers if necessary, and executes no operation if the
81       peer is already being tracked. A single invocation of
82       sd_bus_track_remove_name() removes the reference on the peer again,
83       regardless how many times sd_bus_track_add_name() was called before. If
84       operating in recursive mode, the number of times
85       sd_bus_track_add_name() is invoked for the same peer name is counted
86       and sd_bus_track_remove_name() must be called the same number of times
87       before the peer is not tracked anymore, with the exception when the
88       tracked peer vanishes from the bus, in which case the count is
89       irrelevant and the tracking of the specific peer is immediately
90       removed.  sd_bus_track_get_recursive() may be used to determine whether
91       the bus peer tracking object is operating in recursive mode.
92       sd_bus_track_set_recursive() may be used to enable or disable recursive
93       mode. By default a bus peer tracking object operates in non-recursive
94       mode, and sd_bus_track_get_recursive() for a newly allocated object
95       hence returns a value equal to zero. Use sd_bus_track_set_recursive()
96       to enable recursive mode, right after allocation. It takes a boolean
97       argument to enable or disable recursive mode. Note that tracking
98       objects for which sd_bus_track_add_name() was already invoked at least
99       once (and which hence track already one or more peers) may not be
100       switched from recursive to non-recursive mode anymore.
101
102       sd_bus_track_get_bus() returns the bus object the bus peer tracking
103       object belongs to. It returns the bus object initially passed to
104       sd_bus_track_new() when the object was allocated.
105
106       sd_bus_track_get_userdata() returns the generic user data pointer set
107       on the bus peer tracking object at the time of creation using
108       sd_bus_track_new() or at a later time, using
109       sd_bus_track_set_userdata().
110

RETURN VALUE

112       On success, sd_bus_track_new() and sd_bus_track_set_recursive() return
113       0 or a positive integer. On failure, they return a negative errno-style
114       error code.
115
116       sd_bus_track_ref() always returns the argument.
117
118       sd_bus_track_unref() always returns NULL.
119
120       sd_bus_track_get_recursive() returns 0 if non-recursive mode is
121       selected (default), and greater than 0 if recursive mode is selected.
122       On failure a negative errno-style error code is returned.
123
124       sd_bus_track_get_bus() returns the bus object associated to the bus
125       peer tracking object.
126
127       sd_bus_track_get_userdata() returns the generic user data pointer
128       associated with the bus peer tracking object.
129       sd_bus_track_set_userdata() returns the previous user data pointer set.
130

REFERENCE OWNERSHIP

132       The sd_bus_track_new() function creates a new object and the caller
133       owns the sole reference. When not needed anymore, this reference should
134       be destroyed with sd_bus_track_unref().
135
136   Errors
137       Returned errors may indicate the following problems:
138
139       -EBUSY
140           Bus peers have already been added to the bus peer tracking object
141           and sd_bus_track_set_recursive() was called to change tracking
142           mode.
143
144       -EINVAL
145           Specified parameter is invalid (NULL in case of output parameters).
146
147       -ENOMEM
148           Memory allocation failed.
149

NOTES

151       These APIs are implemented as a shared library, which can be compiled
152       and linked to with the libsystemd pkg-config(1) file.
153

SEE ALSO

155       systemd(1), sd-bus(3) sd_bus_track_add_name(3)
156

NOTES

158        1. Clean-up Variable Attribute
159           https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
160
161
162
163systemd 249                                                SD_BUS_TRACK_NEW(3)
Impressum