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