Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_track_add_name.3

raw
1 '\" t
2 .TH "SD_BUS_TRACK_ADD_NAME" "3" "" "systemd 261~rc3" "sd_bus_track_add_name"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_track_add_name, sd_bus_track_add_sender, sd_bus_track_remove_name, sd_bus_track_remove_sender, sd_bus_track_count, sd_bus_track_count_sender, sd_bus_track_count_name, sd_bus_track_contains, sd_bus_track_first, sd_bus_track_next \- Add, remove and retrieve bus peers tracked in a bus peer tracking object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_track_add_name('u
32 .BI "int sd_bus_track_add_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
33 .HP \w'int\ sd_bus_track_add_sender('u
34 .BI "int sd_bus_track_add_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
35 .HP \w'int\ sd_bus_track_remove_name('u
36 .BI "int sd_bus_track_remove_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
37 .HP \w'int\ sd_bus_track_remove_sender('u
38 .BI "int sd_bus_track_remove_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
39 .HP \w'unsigned\ sd_bus_track_count('u
40 .BI "unsigned sd_bus_track_count(sd_bus_track*\ " "t" ");"
41 .HP \w'int\ sd_bus_track_count_name('u
42 .BI "int sd_bus_track_count_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
43 .HP \w'int\ sd_bus_track_count_sender('u
44 .BI "int sd_bus_track_count_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");"
45 .HP \w'int\ sd_bus_track_contains('u
46 .BI "int sd_bus_track_contains(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");"
47 .HP \w'const\ char*\ sd_bus_track_first('u
48 .BI "const char* sd_bus_track_first(sd_bus_track*\ " "t" ");"
49 .HP \w'const\ char*\ sd_bus_track_next('u
50 .BI "const char* sd_bus_track_next(sd_bus_track*\ " "t" ");"
51 .SH "DESCRIPTION"
52 .PP
53 \fBsd_bus_track_add_name()\fR
54 adds a peer to track to a bus peer tracking object\&. The first argument should refer to a bus peer tracking object created with
55 \fBsd_bus_track_new\fR(3), the second name should refer to a D\-Bus peer name to track, either in unique or well\-known service format\&. If the name is not tracked yet it will be added to the list of names to track\&. If it already is being tracked and non\-recursive mode is enabled, no operation is executed by this call\&. If recursive mode is enabled a per\-name counter is increased by one each time this call is invoked, and
56 \fBsd_bus_track_remove_name()\fR
57 has to be called as many times as
58 \fBsd_bus_track_add_name()\fR
59 was invoked before in order to stop tracking of the name\&. Use
60 \fBsd_bus_track_set_recursive\fR(3)
61 to switch from the default non\-recursive mode to recursive mode, or back\&. Note that the specified name is tracked as it is, well\-known names are not resolved to unique names by this call\&. Note that multiple bus peer tracking objects may track the same name\&.
62 .PP
63 \fBsd_bus_track_remove_name()\fR
64 undoes the effect of
65 \fBsd_bus_track_add_name()\fR
66 and removes a bus peer name from the list of peers to watch\&. Depending on whether non\-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove the name fully from the tracking object, or will simply decrement the per\-name counter by one, removing the name only when the counter reaches zero (see above)\&. Note that a bus peer disconnecting from the bus will implicitly remove its names fully from the bus peer tracking object, regardless of the current per\-name counter\&.
67 .PP
68 \fBsd_bus_track_add_sender()\fR
69 and
70 \fBsd_bus_track_remove_sender()\fR
71 are similar to
72 \fBsd_bus_track_add_name()\fR
73 and
74 \fBsd_bus_track_remove_name()\fR
75 but take a bus message as argument\&. The sender of this bus message is determined and added to/removed from the bus peer tracking object\&. As messages always originate from unique names, and never from well\-known names this means that this call will effectively only add unique names to the bus peer tracking object\&.
76 .PP
77 \fBsd_bus_track_count()\fR
78 returns the number of names currently being tracked by the specified bus peer tracking object\&. Note that this function always returns the actual number of names tracked, and hence if
79 \fBsd_bus_track_add_name()\fR
80 has been invoked multiple times for the same name it is only counted as one, regardless of whether recursive mode is used or not\&.
81 .PP
82 \fBsd_bus_track_count_name()\fR
83 returns the current per\-name counter for the specified name\&. If non\-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been added to the tracking object before, or not\&. If recursive mode has been enabled, values larger than 1 may be returned too, in case
84 \fBsd_bus_track_add_name()\fR
85 has been called multiple times for the same name\&.
86 .PP
87 \fBsd_bus_track_count_sender()\fR
88 is similar to
89 \fBsd_bus_track_count_name()\fR, but takes a bus message object and returns the per\-name counter matching the sender of the message\&.
90 .PP
91 \fBsd_bus_track_contains()\fR
92 may be used to determine whether the specified name has been added at least once to the specified bus peer tracking object\&.
93 .PP
94 \fBsd_bus_track_first()\fR
95 and
96 \fBsd_bus_track_next()\fR
97 may be used to enumerate all names currently being tracked by the passed bus peer tracking object\&.
98 \fBsd_bus_track_first()\fR
99 returns the first entry in the object, and resets an internally maintained read index\&. Each subsequent invocation of
100 \fBsd_bus_track_next()\fR
101 returns the next name contained in the bus object\&. If the end is reached
102 \fBNULL\fR
103 is returned\&. If no names have been added to the object yet
104 \fBsd_bus_track_first()\fR
105 will return
106 \fBNULL\fR
107 immediately\&. The order in which names are returned is undefined; in particular which name is considered the first returned is not defined\&. If recursive mode is enabled and the same name has been added multiple times to the bus peer tracking object it is only returned once by this enumeration\&. If new names are added to or existing names removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation of
108 \fBsd_bus_track_next()\fR
109 as
110 \fBNULL\fR
111 is returned\&.
112 .SH "RETURN VALUE"
113 .PP
114 On success,
115 \fBsd_bus_track_add_name()\fR
116 and
117 \fBsd_bus_track_add_sender()\fR
118 return 0 if the specified name has already been added to the bus peer tracking object before and positive if it has not\&. On failure, they return a negative errno\-style error code\&.
119 .PP
120 \fBsd_bus_track_remove_name()\fR
121 and
122 \fBsd_bus_track_remove_sender()\fR
123 return positive if the specified name was previously tracked by the bus peer tracking object and has now been removed\&. In non\-recursive mode, 0 is returned if the specified name was not being tracked yet\&. In recursive mode
124 \fB\-EUNATCH\fR
125 is returned in this case\&. On failure, they return a negative errno\-style error code\&.
126 .PP
127 \fBsd_bus_track_count()\fR
128 returns the number of names currently being tracked, or 0 on failure\&.
129 .PP
130 \fBsd_bus_track_count_name()\fR
131 and
132 \fBsd_bus_track_count_sender()\fR
133 return the current per\-name counter for the specified name or the sender of the specified message\&. Zero is returned for names that are not being tracked yet, a positive value for names added at least once\&. Larger values than 1 are only returned in recursive mode\&. On failure, a negative errno\-style error code is returned\&.
134 .PP
135 \fBsd_bus_track_contains()\fR
136 returns the passed name if it exists in the bus peer tracking object\&. On failure, and if the name has not been added yet
137 \fBNULL\fR
138 is returned\&.
139 .PP
140 \fBsd_bus_track_first()\fR
141 and
142 \fBsd_bus_track_next()\fR
143 return the first/next name contained in the bus peer tracking object, and
144 \fBNULL\fR
145 if the end of the enumeration is reached and on error\&.
146 .SS "Errors"
147 .PP
148 Returned errors may indicate the following problems:
149 .PP
150 \fB\-EUNATCH\fR
151 .RS 4
152 \fBsd_bus_track_remove_name()\fR
153 or
154 \fBsd_bus_track_remove_sender()\fR
155 have been invoked for a name not previously added to the bus peer object\&.
156 .RE
157 .PP
158 \fB\-EINVAL\fR
159 .RS 4
160 Specified parameter is invalid\&.
161 .RE
162 .PP
163 \fB\-ENOMEM\fR
164 .RS 4
165 Memory allocation failed\&.
166 .RE
167 .SH "NOTES"
168 .PP
169 Functions described here are available as a shared library, which can be compiled against and linked to with the
170 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
171 file\&.
172 .PP
173 The code described here uses
174 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
175 \fBsetenv\fR(3)
176 from a parallel thread\&. It is recommended to only do calls to
177 \fBsetenv()\fR
178 from an early phase of the program when no other threads have been started\&.
179 .SH "HISTORY"
180 .PP
181 \fBsd_bus_track_add_name()\fR,
182 \fBsd_bus_track_add_sender()\fR,
183 \fBsd_bus_track_remove_name()\fR,
184 \fBsd_bus_track_remove_sender()\fR,
185 \fBsd_bus_track_count()\fR,
186 \fBsd_bus_track_count_name()\fR,
187 \fBsd_bus_track_count_sender()\fR,
188 \fBsd_bus_track_contains()\fR,
189 \fBsd_bus_track_first()\fR, and
190 \fBsd_bus_track_next()\fR
191 were added in version 232\&.
192 .SH "SEE ALSO"
193 .PP
194 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_track_new\fR(3)