1SD_BUS_TRACK_ADD_NAME(3)     sd_bus_track_add_name    SD_BUS_TRACK_ADD_NAME(3)
2
3
4

NAME

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

SYNOPSIS

13       #include <systemd/sd-bus.h>
14
15       int sd_bus_track_add_name(sd_bus_track* t, const char* name);
16
17       int sd_bus_track_add_sender(sd_bus_track* t, sd_bus_message* message);
18
19       int sd_bus_track_remove_name(sd_bus_track* t, const char* name);
20
21       int sd_bus_track_remove_sender(sd_bus_track* t,
22                                      sd_bus_message* message);
23
24       unsigned sd_bus_track_count(sd_bus_track* t);
25
26       int sd_bus_track_count_name(sd_bus_track* t, const char* name);
27
28       int sd_bus_track_count_sender(sd_bus_track* t,
29                                     sd_bus_message* message);
30
31       int sd_bus_track_contains(sd_bus_track* t, const char* name);
32
33       const char* sd_bus_track_first(sd_bus_track* t);
34
35       const char* sd_bus_track_next(sd_bus_track* t);
36

DESCRIPTION

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
54       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
64       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
72       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
79       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
87       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
91       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
95       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

RETURN VALUE

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
117       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
124       sd_bus_track_count() returns the number of names currently being
125       tracked, or 0 on failure.
126
127       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
134       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
138       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
145       -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
150       -EINVAL
151           Specified parameter is invalid.
152
153       -ENOMEM
154           Memory allocation failed.
155

NOTES

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

SEE ALSO

161       systemd(1), sd-bus(3), sd_bus_track_new(3)
162
163
164
165systemd 239                                           SD_BUS_TRACK_ADD_NAME(3)
Impressum