# sd_bus_track_new

## 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.
    


## NOTES



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


* * *