diff --git a/Makefile-man.am b/Makefile-man.am index bf8de1e58f..ef5077cc5a 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -52,6 +52,8 @@ MANPAGES += \ man/sd_bus_path_encode.3 \ man/sd_bus_process.3 \ man/sd_bus_request_name.3 \ + man/sd_bus_track_add_name.3 \ + man/sd_bus_track_new.3 \ man/sd_event_add_child.3 \ man/sd_event_add_defer.3 \ man/sd_event_add_io.3 \ @@ -332,6 +334,23 @@ MANPAGES_ALIAS += \ man/sd_bus_path_encode_many.3 \ man/sd_bus_ref.3 \ man/sd_bus_release_name.3 \ + man/sd_bus_track_add_sender.3 \ + man/sd_bus_track_contains.3 \ + man/sd_bus_track_count.3 \ + man/sd_bus_track_count_name.3 \ + man/sd_bus_track_count_sender.3 \ + man/sd_bus_track_first.3 \ + man/sd_bus_track_get_bus.3 \ + man/sd_bus_track_get_recursive.3 \ + man/sd_bus_track_get_userdata.3 \ + man/sd_bus_track_next.3 \ + man/sd_bus_track_ref.3 \ + man/sd_bus_track_remove_name.3 \ + man/sd_bus_track_remove_sender.3 \ + man/sd_bus_track_set_recursive.3 \ + man/sd_bus_track_set_userdata.3 \ + man/sd_bus_track_unref.3 \ + man/sd_bus_track_unrefp.3 \ man/sd_bus_unref.3 \ man/sd_bus_unrefp.3 \ man/sd_event.3 \ @@ -665,6 +684,23 @@ man/sd_bus_path_decode_many.3: man/sd_bus_path_encode.3 man/sd_bus_path_encode_many.3: man/sd_bus_path_encode.3 man/sd_bus_ref.3: man/sd_bus_new.3 man/sd_bus_release_name.3: man/sd_bus_request_name.3 +man/sd_bus_track_add_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_contains.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count_name.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_first.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_get_bus.3: man/sd_bus_track_new.3 +man/sd_bus_track_get_recursive.3: man/sd_bus_track_new.3 +man/sd_bus_track_get_userdata.3: man/sd_bus_track_new.3 +man/sd_bus_track_next.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_ref.3: man/sd_bus_track_new.3 +man/sd_bus_track_remove_name.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_remove_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_set_recursive.3: man/sd_bus_track_new.3 +man/sd_bus_track_set_userdata.3: man/sd_bus_track_new.3 +man/sd_bus_track_unref.3: man/sd_bus_track_new.3 +man/sd_bus_track_unrefp.3: man/sd_bus_track_new.3 man/sd_bus_unref.3: man/sd_bus_new.3 man/sd_bus_unrefp.3: man/sd_bus_new.3 man/sd_event.3: man/sd_event_new.3 @@ -1300,6 +1336,57 @@ man/sd_bus_ref.html: man/sd_bus_new.html man/sd_bus_release_name.html: man/sd_bus_request_name.html $(html-alias) +man/sd_bus_track_add_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_contains.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count_name.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_first.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_get_bus.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_get_recursive.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_get_userdata.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_next.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_ref.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_remove_name.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_remove_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_set_recursive.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_set_userdata.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_unref.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_unrefp.html: man/sd_bus_track_new.html + $(html-alias) + man/sd_bus_unref.html: man/sd_bus_new.html $(html-alias) @@ -2559,6 +2646,8 @@ EXTRA_DIST += \ man/sd_bus_path_encode.xml \ man/sd_bus_process.xml \ man/sd_bus_request_name.xml \ + man/sd_bus_track_add_name.xml \ + man/sd_bus_track_new.xml \ man/sd_event_add_child.xml \ man/sd_event_add_defer.xml \ man/sd_event_add_io.xml \ diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 336dd33ea0..66b1c96c15 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -44,7 +44,7 @@ sd-bus - A lightweight D-Bus and kdbus client library + A lightweight D-Bus IPC client library @@ -61,49 +61,40 @@ Description - sd-bus.h provides an implementation - of a D-Bus client. It can interoperate both with the traditional - dbus-daemon1, - and with kdbus. See + sd-bus.h provides an implementation of a D-Bus IPC client. See - for more information about the big picture. + for more information about D-Bus IPC. - - Interfaces described here have not been declared stable yet, - and are not accessible from libsystemd.so. - This documentation is provided in hope it might be useful for - developers, without any guarantees of availability or stability. - - - See + sd-bus-errors3, + sd_bus_creds_get_pid3, + sd_bus_creds_new_from_pid3, sd_bus_default3, - sd_bus_new3, - sd_bus_request_name3, - sd_bus_start3, + sd_bus_error3, + sd_bus_error_add_map3, + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, sd_bus_message_append3, - sd_bus_message_append_basic3, sd_bus_message_append_array3, + sd_bus_message_append_basic3, sd_bus_message_append_string_memfd3, sd_bus_message_append_strv3, sd_bus_message_can_send3, sd_bus_message_get_cookie3, sd_bus_message_get_monotonic_usec3, + sd_bus_negotiate_fds3, + sd_bus_new3, + sd_bus_path_encode3, + sd_bus_request_name3, sd_bus_send3, sd_bus_set_address3, + sd_bus_set_allow_interactive_authorization3 sd_bus_set_description3, sd_bus_set_prepare3, - sd_bus_creds_get_pid3, - sd_bus_creds_new_from_pid3, - sd_bus_get_name_creds3, - sd_bus_get_owner_creds3, - sd_bus_negotiate_fds3, - sd_bus_path_encode3, - sd-bus-errors3, - sd_bus_error3, - sd_bus_error_add_map3, - sd_bus_set_allow_interactive_authorization3 + sd_bus_start3, + sd_bus_track_add_name3, + sd_bus_track_new3, for more information about the functions available. @@ -114,9 +105,9 @@ systemd1, sd-event3, + busctl1, dbus-daemon1, - dbus-send1, - gdbus + dbus-send1 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 + + + + diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml new file mode 100644 index 0000000000..60e2e77f75 --- /dev/null +++ b/man/sd_bus_track_new.xml @@ -0,0 +1,263 @@ + + + + + + + + + sd_bus_track_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_track_new + 3 + + + + sd_bus_track_new + sd_bus_track_ref + sd_bus_track_unref + sd_bus_track_unrefp + sd_bus_track_set_recursive + sd_bus_track_get_recursive + sd_bus_track_get_bus + sd_bus_track_get_userdata + sd_bus_track_set_userdata + + Track bus peers + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_track_new + sd_bus* bus + sd_bus_track** ret + sd_bus_track_handler_t handler + void* userdata + + + + sd_bus_track *sd_bus_track_ref + sd_bus_track *t + + + + sd_bus_track *sd_bus_track_unref + sd_bus_track *t + + + + void sd_bus_track_unrefp + sd_bus_track **t + + + + int sd_bus_track_get_recursive + sd_bus_track *t + + + + int sd_bus_track_set_recursive + sd_bus_track *t + int b + + + + sd_bus* sd_bus_track_get_bus + sd_bus_track *t + + + + void* sd_bus_track_get_userdata + sd_bus_track *t + + + + void* sd_bus_track_set_userdata + sd_bus_track *t + void *userdata + + + + + + + Description + + sd_bus_track_new() creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the *ret parameter. After use, the object should be freed + again by dropping the acquired reference with sd_bus_track_unref() (see below). A bus peer + tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of + one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as + long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers + have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to + specific bus peers are added via + sd_bus_track_add_name3 or + sd_bus_track_add_sender(). They may be dropped again via + sd_bus_track_remove_name() and + sd_bus_track_remove_sender(). Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the handler may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + sd_bus_track_remove_name() or implicitly because the peer disconnected from the bus. The final + argument userdata may be used to attach a generic user data pointer to the object. This + pointer is passed to the handler callback when it is invoked. + + sd_bus_track_ref() creates a new reference to a bus peer tracking object. This object + will not be destroyed until sd_bus_track_unref() has been called as many times plus once + more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to + sd_bus_track_ref() or sd_bus_track_unref() on the same object are + illegal. + + sd_bus_track_unref() destroys a reference to a bus peer tracking object. + + sd_bus_track_unrefp() is similar to sd_bus_track_unref() but takes + a pointer to a pointer to an sd_bus_track object. This call is useful in conjunction with GCC's and + LLVM's Clean-up Variable + Attribute. Note that this function is defined as inline function. + + sd_bus_track_ref(), sd_bus_track_unref() and + sd_bus_track_unrefp() execute no operation if the passed in bus peer tracking object is + NULL. + + Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may + optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked + or not tracked. In this mode invoking sd_bus_track_add_name() multiple times in a row for the + same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if + necessary, and executes no operation if the peer is already being tracked. A single invocation of + sd_bus_track_remove_name() removes the reference on the peer again, regardless how many times + sd_bus_track_add_name() was called before. If operating in recursive mode, the number of times + sd_bus_track_add_name() is invoked for the same peer name is counted and + sd_bus_track_remove_name() must be called the same number of times before the peer is not + tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is + irrelevant and the tracking of the specific peer is immediately + removed. sd_bus_track_get_recursive() may be used to determine whether the bus peer tracking + object is operating in recursive mode. sd_bus_track_set_recursive() may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + sd_bus_track_get_recursive() for a newly allocated object hence returns a value equal to + zero. Use sd_bus_track_set_recursive() to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + sd_bus_track_add_name() was already invoked at least once (and which hence track already one + or more peers) may not be switched from recursive to non-recursive mode anymore. + + sd_bus_track_get_bus() returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to sd_bus_track_new() when the object was + allocated. + + sd_bus_track_get_userdata() returns the generic user data pointer set on the bus peer + tracking object at the time of creation using sd_bus_track_new() or at a later time, using + sd_bus_track_set_userdata(). + + + + Return Value + + On success, sd_bus_track_new() and sd_bus_track_set_recursive() + return 0 or a positive integer. On failure, they return a negative errno-style error code. + + sd_bus_track_ref() always returns the argument. + + sd_bus_track_unref() always returns NULL. + + sd_bus_track_get_recursive() returns 0 if non-recursive mode is selected (default), and + greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned. + + sd_bus_track_get_bus() returns the bus object associated to the bus peer tracking + object. + + sd_bus_track_get_userdata() returns the generic user data pointer associated with the + bus peer tracking object. sd_bus_track_set_userdata() returns the previous user data pointer + set. + + + + + Reference ownership + + The sd_bus_track_new() function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + sd_bus_track_unref(). + + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EBUSY + + Bus peers have already been added to the bus peer tracking object and + sd_bus_track_set_recursive() was called to change tracking mode. + + + + -EINVAL + + Specified parameter is invalid + (NULL in case of output + parameters). + + + + -ENOMEM + + Memory allocation failed. + + + + + + + Notes + + sd_bus_track_new() 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_add_name3 + + + +