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