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