From ecddb2b586d1b69e5538fb85262d2b9e6d253ac0 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 15 Aug 2016 14:59:59 +0200 Subject: man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically. --- man/sd_bus_track_add_name.xml | 261 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 261 insertions(+) create mode 100644 man/sd_bus_track_add_name.xml (limited to 'man/sd_bus_track_add_name.xml') diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml new file mode 100644 index 0000000000..6a5e344cb1 --- /dev/null +++ b/man/sd_bus_track_add_name.xml @@ -0,0 +1,261 @@ + + + + + + + + + sd_bus_track_add_name + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_track_add_name + 3 + + + + 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 + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_track_add_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_add_sender + sd_bus_track* t + sd_bus_message* message + + + + int sd_bus_track_remove_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_remove_sender + sd_bus_track* t + sd_bus_message* message + + + + unsigned sd_bus_track_count + sd_bus_track* t + + + + int sd_bus_track_count_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_count_sender + sd_bus_track* t + sd_bus_message* message + + + + int sd_bus_track_contains + sd_bus_track* t + const char* name + + + + const char* sd_bus_track_first + sd_bus_track* t + + + + const char* sd_bus_track_next + sd_bus_track* t + + + + + + + Description + + sd_bus_track_add_name() adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + sd_bus_track_new3, 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 sd_bus_track_remove_name() has to be called as many + times as sd_bus_track_add_name() was invoked before in order to stop tracking of the name. Use + sd_bus_track_set_recursive3 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. + + sd_bus_track_remove_name() undoes the effect of + sd_bus_track_add_name() 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. + + sd_bus_track_add_sender() and sd_bus_track_remove_sender() are + similar to sd_bus_track_add_name() and sd_bus_track_remove_name() 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. + + sd_bus_track_count() 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 sd_bus_track_add_name() has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not. + + sd_bus_track_count_name() 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 sd_bus_track_add_name() has been called multiple times for the same + name. + + sd_bus_track_count_sender() is similar to + sd_bus_track_count_name(), but takes a bus message object and returns the per-name counter + matching the sender of the message. + + sd_bus_track_contains() may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object. + + sd_bus_track_first() and sd_bus_track_next() may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. sd_bus_track_first() returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of sd_bus_track_next() returns the next name + contained in the bus object. If the end is reached NULL is returned. If no names have been + added to the object yet sd_bus_track_first() will return NULL + 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 sd_bus_track_next() as NULL is returned. + + + + Return Value + + On success, sd_bus_track_add_name() and sd_bus_track_add_sender() + return 0 if the specified name has already been added to the bus peer tracking object before and positive if it + hasn't. On failure, they return a negative errno-style error code. + + sd_bus_track_remove_name() and sd_bus_track_remove_sender() 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 + -EUNATCH is returned in this case. On failure, they return a negative errno-style error + code. + + sd_bus_track_count() returns the number of names currently being tracked, or 0 on + failure. + + sd_bus_track_count_name() and sd_bus_track_count_sender() 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. + + sd_bus_track_contains() returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet NULL is returned. + + sd_bus_track_first() and sd_bus_track_next() return the first/next + name contained in the bus peer tracking object, and NULL if the end of the enumeration is + reached and on error. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EUNATCH + + sd_bus_track_remove_name() or + sd_bus_track_remove_sender() have been invoked for a name not previously added to the bus + peer object. + + + + -EINVAL + + Specified parameter is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + Notes + + sd_bus_track_add_name() and the other calls described here are available as a shared library, + which can be compiled and linked to with the libsystemd pkg-config1 file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_track_new3 + + + + -- cgit v1.2.3-54-g00ecf