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 m[blue]Clean-up Variable Attributem. 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().
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.
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().
Returned errors may indicate the following problems:
These APIs are implemented as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.
systemd(1), sd-bus(3) sd_bus_track_add_name(3)