'\" t .TH "SD_BUS_TRACK_ADD_NAME" "3" "" "systemd 256.6" "sd_bus_track_add_name" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" 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 .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'int\ sd_bus_track_add_name('u .BI "int sd_bus_track_add_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");" .HP \w'int\ sd_bus_track_add_sender('u .BI "int sd_bus_track_add_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");" .HP \w'int\ sd_bus_track_remove_name('u .BI "int sd_bus_track_remove_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");" .HP \w'int\ sd_bus_track_remove_sender('u .BI "int sd_bus_track_remove_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");" .HP \w'unsigned\ sd_bus_track_count('u .BI "unsigned sd_bus_track_count(sd_bus_track*\ " "t" ");" .HP \w'int\ sd_bus_track_count_name('u .BI "int sd_bus_track_count_name(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");" .HP \w'int\ sd_bus_track_count_sender('u .BI "int sd_bus_track_count_sender(sd_bus_track*\ " "t" ", sd_bus_message*\ " "message" ");" .HP \w'int\ sd_bus_track_contains('u .BI "int sd_bus_track_contains(sd_bus_track*\ " "t" ", const\ char*\ " "name" ");" .HP \w'const\ char*\ sd_bus_track_first('u .BI "const char* sd_bus_track_first(sd_bus_track*\ " "t" ");" .HP \w'const\ char*\ sd_bus_track_next('u .BI "const char* sd_bus_track_next(sd_bus_track*\ " "t" ");" .SH "DESCRIPTION" .PP \fBsd_bus_track_add_name()\fR adds a peer to track to a bus peer tracking object\&. The first argument should refer to a bus peer tracking object created with \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 \fBsd_bus_track_remove_name()\fR has to be called as many times as \fBsd_bus_track_add_name()\fR was invoked before in order to stop tracking of the name\&. Use \fBsd_bus_track_set_recursive\fR(3) 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\&. .PP \fBsd_bus_track_remove_name()\fR undoes the effect of \fBsd_bus_track_add_name()\fR 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\&. .PP \fBsd_bus_track_add_sender()\fR and \fBsd_bus_track_remove_sender()\fR are similar to \fBsd_bus_track_add_name()\fR and \fBsd_bus_track_remove_name()\fR 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\&. .PP \fBsd_bus_track_count()\fR 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 \fBsd_bus_track_add_name()\fR has been invoked multiple times for the same name it is only counted as one, regardless if recursive mode is used or not\&. .PP \fBsd_bus_track_count_name()\fR 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 \fBsd_bus_track_add_name()\fR has been called multiple times for the same name\&. .PP \fBsd_bus_track_count_sender()\fR is similar to \fBsd_bus_track_count_name()\fR, but takes a bus message object and returns the per\-name counter matching the sender of the message\&. .PP \fBsd_bus_track_contains()\fR may be used to determine whether the specified name has been added at least once to the specified bus peer tracking object\&. .PP \fBsd_bus_track_first()\fR and \fBsd_bus_track_next()\fR may be used to enumerate all names currently being tracked by the passed bus peer tracking object\&. \fBsd_bus_track_first()\fR returns the first entry in the object, and resets an internally maintained read index\&. Each subsequent invocation of \fBsd_bus_track_next()\fR returns the next name contained in the bus object\&. If the end is reached \fBNULL\fR is returned\&. If no names have been added to the object yet \fBsd_bus_track_first()\fR will return \fBNULL\fR 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 \fBsd_bus_track_next()\fR as \fBNULL\fR is returned\&. .SH "RETURN VALUE" .PP On success, \fBsd_bus_track_add_name()\fR and \fBsd_bus_track_add_sender()\fR return 0 if the specified name has already been added to the bus peer tracking object before and positive if it hasn\*(Aqt\&. On failure, they return a negative errno\-style error code\&. .PP \fBsd_bus_track_remove_name()\fR and \fBsd_bus_track_remove_sender()\fR 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 \fB\-EUNATCH\fR is returned in this case\&. On failure, they return a negative errno\-style error code\&. .PP \fBsd_bus_track_count()\fR returns the number of names currently being tracked, or 0 on failure\&. .PP \fBsd_bus_track_count_name()\fR and \fBsd_bus_track_count_sender()\fR 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\&. .PP \fBsd_bus_track_contains()\fR returns the passed name if it exists in the bus peer tracking object\&. On failure, and if the name has not been added yet \fBNULL\fR is returned\&. .PP \fBsd_bus_track_first()\fR and \fBsd_bus_track_next()\fR return the first/next name contained in the bus peer tracking object, and \fBNULL\fR if the end of the enumeration is reached and on error\&. .SS "Errors" .PP Returned errors may indicate the following problems: .PP \fB\-EUNATCH\fR .RS 4 \fBsd_bus_track_remove_name()\fR or \fBsd_bus_track_remove_sender()\fR have been invoked for a name not previously added to the bus peer object\&. .RE .PP \fB\-EINVAL\fR .RS 4 Specified parameter is invalid\&. .RE .PP \fB\-ENOMEM\fR .RS 4 Memory allocation failed\&. .RE .SH "NOTES" .PP Functions described here are available as a shared library, which can be compiled against and linked to with the \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) file\&. .PP The code described here uses \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 \fBsetenv\fR(3) from a parallel thread\&. It is recommended to only do calls to \fBsetenv()\fR from an early phase of the program when no other threads have been started\&. .SH "HISTORY" .PP \fBsd_bus_track_add_name()\fR, \fBsd_bus_track_add_sender()\fR, \fBsd_bus_track_remove_name()\fR, \fBsd_bus_track_remove_sender()\fR, \fBsd_bus_track_count()\fR, \fBsd_bus_track_count_name()\fR, \fBsd_bus_track_count_sender()\fR, \fBsd_bus_track_contains()\fR, \fBsd_bus_track_first()\fR, and \fBsd_bus_track_next()\fR were added in version 232\&. .SH "SEE ALSO" .PP \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_track_new\fR(3)