man/sd_bus_track_new.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_bus_track_new" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_bus_track_new</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_bus_track_new</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_bus_track_new</refname>
  23     <refname>sd_bus_track_ref</refname>
  24     <refname>sd_bus_track_unref</refname>
  25     <refname>sd_bus_track_unrefp</refname>
  26     <refname>sd_bus_track_set_recursive</refname>
  27     <refname>sd_bus_track_get_recursive</refname>
  28     <refname>sd_bus_track_get_bus</refname>
  29     <refname>sd_bus_track_get_userdata</refname>
  30     <refname>sd_bus_track_set_userdata</refname>
  31
  32     <refpurpose>Track bus peers</refpurpose>
  33   </refnamediv>
  34
  35   <refsynopsisdiv>
  36     <funcsynopsis>
  37       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  38
  39       <funcprototype>
  40         <funcdef>int <function>sd_bus_track_new</function></funcdef>
  41         <paramdef>sd_bus* <parameter>bus</parameter></paramdef>
  42         <paramdef>sd_bus_track** <parameter>ret</parameter></paramdef>
  43         <paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef>
  44         <paramdef>void* <parameter>userdata</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef>
  49         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  50       </funcprototype>
  51
  52       <funcprototype>
  53         <funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef>
  54         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  55       </funcprototype>
  56
  57       <funcprototype>
  58         <funcdef>void <function>sd_bus_track_unrefp</function></funcdef>
  59         <paramdef>sd_bus_track **<parameter>t</parameter></paramdef>
  60       </funcprototype>
  61
  62       <funcprototype>
  63         <funcdef>int <function>sd_bus_track_get_recursive</function></funcdef>
  64         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_bus_track_set_recursive</function></funcdef>
  69         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  70         <paramdef>int <parameter>b</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef>
  75         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef>
  80         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef>
  85         <paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
  86         <paramdef>void *userdata</paramdef>
  87       </funcprototype>
  88
  89     </funcsynopsis>
  90   </refsynopsisdiv>
  91
  92   <refsect1>
  93     <title>Description</title>
  94
  95     <para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for
  96     the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed
  97     again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (see below). A bus peer
  98     tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of
  99     one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as
 100     long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers
 101     have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to
 102     specific bus peers are added via
 103     <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
 104     <function>sd_bus_track_add_sender()</function>. They may be dropped again via
 105     <function>sd_bus_track_remove_name()</function> and
 106     <function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically
 107     when they disconnect from the bus.  If non-NULL the <parameter>handler</parameter> may specify a function that is
 108     invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via
 109     <function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final
 110     argument <parameter>userdata</parameter> may be used to attach a generic user data pointer to the object. This
 111     pointer is passed to the handler callback when it is invoked.</para>
 112
 113     <para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object
 114     will not be destroyed until <function>sd_bus_track_unref()</function> has been called as many times plus once
 115     more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to
 116     <function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are
 117     illegal.</para>
 118
 119     <para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para>
 120
 121     <para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes
 122     a pointer to a pointer to an <type>sd_bus_track</type> object. This call is useful in conjunction with GCC's and
 123     LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable
 124     Attribute</ulink>. Note that this function is defined as inline function.</para>
 125
 126     <para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and
 127     <function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is
 128     <constant>NULL</constant>.</para>
 129
 130     <para>Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may
 131     optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked
 132     or not tracked. In this mode invoking <function>sd_bus_track_add_name()</function> multiple times in a row for the
 133     same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if
 134     necessary, and executes no operation if the peer is already being tracked. A single invocation of
 135     <function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times
 136     <function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times
 137     <function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and
 138     <function>sd_bus_track_remove_name()</function> must be called the same number of times before the peer is not
 139     tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is
 140     irrelevant and the tracking of the specific peer is immediately
 141     removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking
 142     object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or
 143     disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and
 144     <function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to
 145     zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It
 146     takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which
 147     <function>sd_bus_track_add_name()</function> was already invoked at least once (and which hence track already one
 148     or more peers) may not be switched from recursive to non-recursive mode anymore.</para>
 149
 150     <para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs
 151     to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was
 152     allocated.</para>
 153
 154     <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer
 155     tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using
 156     <function>sd_bus_track_set_userdata()</function>.</para>
 157   </refsect1>
 158
 159   <refsect1>
 160     <title>Return Value</title>
 161
 162     <para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function>
 163     return 0 or a positive integer. On failure, they return a negative errno-style error code.</para>
 164
 165     <para><function>sd_bus_track_ref()</function> always returns the argument.</para>
 166
 167     <para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para>
 168
 169     <para><function>sd_bus_track_get_recursive()</function> returns 0 if non-recursive mode is selected (default), and
 170     greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.</para>
 171
 172     <para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking
 173     object.</para>
 174
 175     <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the
 176     bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer
 177     set.</para>
 178
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>Reference ownership</title>
 183
 184     <para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole
 185     reference. When not needed anymore, this reference should be destroyed with
 186     <function>sd_bus_track_unref()</function>.
 187     </para>
 188   </refsect1>
 189
 190   <refsect1>
 191     <title>Errors</title>
 192
 193     <para>Returned errors may indicate the following problems:</para>
 194
 195     <variablelist>
 196
 197       <varlistentry>
 198         <term><constant>-EBUSY</constant></term>
 199
 200         <listitem><para>Bus peers have already been added to the bus peer tracking object and
 201         <function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><constant>-EINVAL</constant></term>
 206
 207         <listitem><para>Specified parameter is invalid
 208         (<constant>NULL</constant> in case of output
 209         parameters).</para></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term><constant>-ENOMEM</constant></term>
 214
 215         <listitem><para>Memory allocation failed.</para></listitem>
 216       </varlistentry>
 217
 218     </variablelist>
 219   </refsect1>
 220
 221   <xi:include href="libsystemd-pkgconfig.xml" />
 222
 223   <refsect1>
 224     <title>See Also</title>
 225
 226     <para>
 227       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 228       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 229       <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 230     </para>
 231   </refsect1>
 232
 233 </refentry>