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