| 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) |