1SD_BUS_TRACK_ADD_NAME(3) sd_bus_track_add_name SD_BUS_TRACK_ADD_NAME(3)
2
6 sd_bus_track_add_name, sd_bus_track_add_sender,
7 sd_bus_track_remove_name, sd_bus_track_remove_sender,
8 sd_bus_track_count, sd_bus_track_count_sender, sd_bus_track_count_name,
9 sd_bus_track_contains, sd_bus_track_first, sd_bus_track_next - Add,
10 remove and retrieve bus peers tracked in a bus peer tracking object
11
13 #include <systemd/sd-bus.h>
14 int sd_bus_track_add_name(sd_bus_track* t, const char* name);
16 int sd_bus_track_add_sender(sd_bus_track* t, sd_bus_message* message);
18 int sd_bus_track_remove_name(sd_bus_track* t, const char* name);
20 int sd_bus_track_remove_sender(sd_bus_track* t,
22 sd_bus_message* message);
23 unsigned sd_bus_track_count(sd_bus_track* t);
25 int sd_bus_track_count_name(sd_bus_track* t, const char* name);
27 int sd_bus_track_count_sender(sd_bus_track* t,
29 sd_bus_message* message);
30 int sd_bus_track_contains(sd_bus_track* t, const char* name);
32 const char* sd_bus_track_first(sd_bus_track* t);
34 const char* sd_bus_track_next(sd_bus_track* t);
36
38 sd_bus_track_add_name() adds a peer to track to a bus peer tracking
39 object. The first argument should refer to a bus peer tracking object
40 created with sd_bus_track_new(3), the second name should refer to a
41 D-Bus peer name to track, either in unique or well-known service
42 format. If the name is not tracked yet it will be added to the list of
43 names to track. If it already is being tracked and non-recursive mode
44 is enabled, no operation is executed by this call. If recursive mode is
45 enabled a per-name counter is increased by one each time this call is
46 invoked, and sd_bus_track_remove_name() has to be called as many times
47 as sd_bus_track_add_name() was invoked before in order to stop tracking
48 of the name. Use sd_bus_track_set_recursive(3) to switch from the
49 default non-recursive mode to recursive mode, or back. Note that the
50 specified name is tracked as it is, well-known names are not resolved
51 to unique names by this call. Note that multiple bus peer tracking
52 objects may track the same name.
53 sd_bus_track_remove_name() undoes the effect of sd_bus_track_add_name()
55 and removes a bus peer name from the list of peers to watch. Depending
56 on whether non-recursive or recursive mode is enabled for the bus peer
57 tracking object this call will either remove the name fully from the
58 tracking object, or will simply decrement the per-name counter by one,
59 removing the name only when the counter reaches zero (see above). Note
60 that a bus peer disconnecting from the bus will implicitly remove its
61 names fully from the bus peer tracking object, regardless of the
62 current per-name counter.
63 sd_bus_track_add_sender() and sd_bus_track_remove_sender() are similar
65 to sd_bus_track_add_name() and sd_bus_track_remove_name() but take a
66 bus message as argument. The sender of this bus message is determined
67 and added to/removed from the bus peer tracking object. As messages
68 always originate from unique names, and never from well-known names
69 this means that this call will effectively only add unique names to the
70 bus peer tracking object.
71 sd_bus_track_count() returns the number of names currently being
73 tracked by the specified bus peer tracking object. Note that this
74 function always returns the actual number of names tracked, and hence
75 if sd_bus_track_add_name() has been invoked multiple times for the same
76 name it is only counted as one, regardless if recursive mode is used or
77 not.
78 sd_bus_track_count_name() returns the current per-name counter for the
80 specified name. If non-recursive mode is used this returns either 1 or
81 0, depending on whether the specified name has been added to the
82 tracking object before, or not. If recursive mode has been enabled,
83 values larger than 1 may be returned too, in case
84 sd_bus_track_add_name() has been called multiple times for the same
85 name.
86 sd_bus_track_count_sender() is similar to sd_bus_track_count_name(),
88 but takes a bus message object and returns the per-name counter
89 matching the sender of the message.
90 sd_bus_track_contains() may be used to determine whether the specified
92 name has been added at least once to the specified bus peer tracking
93 object.
94 sd_bus_track_first() and sd_bus_track_next() may be used to enumerate
96 all names currently being tracked by the passed bus peer tracking
97 object. sd_bus_track_first() returns the first entry in the object,
98 and resets an internally maintained read index. Each subsequent
99 invocation of sd_bus_track_next() returns the next name contained in
100 the bus object. If the end is reached NULL is returned. If no names
101 have been added to the object yet sd_bus_track_first() will return NULL
102 immediately. The order in which names are returned is undefined; in
103 particular which name is considered the first returned is not defined.
104 If recursive mode is enabled and the same name has been added multiple
105 times to the bus peer tracking object it is only returned once by this
106 enumeration. If new names are added to or existing names removed from
107 the bus peer tracking object while it is being enumerated the
108 enumeration ends on the next invocation of sd_bus_track_next() as NULL
109 is returned.
110
112 On success, sd_bus_track_add_name() and sd_bus_track_add_sender()
113 return 0 if the specified name has already been added to the bus peer
114 tracking object before and positive if it hasn't. On failure, they
115 return a negative errno-style error code.
116 sd_bus_track_remove_name() and sd_bus_track_remove_sender() return
118 positive if the specified name was previously tracked by the bus peer
119 tracking object and has now been removed. In non-recursive mode, 0 is
120 returned if the specified name was not being tracked yet. In recursive
121 mode -EUNATCH is returned in this case. On failure, they return a
122 negative errno-style error code.
123 sd_bus_track_count() returns the number of names currently being
125 tracked, or 0 on failure.
126 sd_bus_track_count_name() and sd_bus_track_count_sender() return the
128 current per-name counter for the specified name or the sender of the
129 specified message. Zero is returned for names that are not being
130 tracked yet, a positive value for names added at least once. Larger
131 values than 1 are only returned in recursive mode. On failure, a
132 negative errno-style error code is returned.
133 sd_bus_track_contains() returns the passed name if it exists in the bus
135 peer tracking object. On failure, and if the name has not been added
136 yet NULL is returned.
137 sd_bus_track_first() and sd_bus_track_next() return the first/next name
139 contained in the bus peer tracking object, and NULL if the end of the
140 enumeration is reached and on error.
141 Errors
143 Returned errors may indicate the following problems:
144 -EUNATCH
146 sd_bus_track_remove_name() or sd_bus_track_remove_sender() have
147 been invoked for a name not previously added to the bus peer
148 object.
149 -EINVAL
151 Specified parameter is invalid.
152 -ENOMEM
154 Memory allocation failed.
155
157 Functions described here are available as a shared library, which can
158 be compiled against and linked to with the libsystemd pkg-config(1)
159 file.
160 The code described here uses getenv(3), which is declared to be not
162 multi-thread-safe. This means that the code calling the functions
163 described here must not call setenv(3) from a parallel thread. It is
164 recommended to only do calls to setenv() from an early phase of the
165 program when no other threads have been started.
166
168 systemd(1), sd-bus(3), sd_bus_track_new(3)
169systemd 254 SD_BUS_TRACK_ADD_NAME(3)