NAME

       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

SYNOPSIS

       #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_name(3) 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[1]. 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

       Functions described here are available as a shared library, which can be compiled against
       and linked to with the libsystemd pkg-config(1) file.

       The code described here uses getenv(3), which is declared to be not multi-thread-safe.
       This means that the code calling the functions described here must not call setenv(3) from
       a parallel thread. It is recommended to only do calls to setenv() from an early phase of
       the program when no other threads have been started.

HISTORY

       sd_bus_track_new(), sd_bus_track_ref(), sd_bus_track_unref(), sd_bus_track_unrefp(),
       sd_bus_track_get_recursive(), sd_bus_track_set_recursive(), sd_bus_track_get_bus(),
       sd_bus_track_get_userdata(), and sd_bus_track_set_userdata() were added in version 232.

SEE ALSO

       systemd(1), sd-bus(3) sd_bus_track_add_name(3)

NOTES

        1. Clean-up Variable Attribute
           https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html