man/sd_bus_track_new.xml

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