man/sd_bus_new.xml

   1 <?xml version='1.0'?>
   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_new" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_bus_new</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_bus_new</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_bus_new</refname>
  23     <refname>sd_bus_ref</refname>
  24     <refname>sd_bus_unref</refname>
  25     <refname>sd_bus_unrefp</refname>
  26     <refname>sd_bus_close_unref</refname>
  27     <refname>sd_bus_close_unrefp</refname>
  28     <refname>sd_bus_flush_close_unref</refname>
  29     <refname>sd_bus_flush_close_unrefp</refname>
  30
  31     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  32   </refnamediv>
  33
  34   <refsynopsisdiv>
  35     <funcsynopsis>
  36       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_bus_new</function></funcdef>
  40         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  41       </funcprototype>
  42
  43       <funcprototype>
  44         <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
  45         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  46       </funcprototype>
  47
  48       <funcprototype>
  49         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
  50         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>sd_bus *<function>sd_bus_close_unref</function></funcdef>
  55         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef>
  60         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>void <function>sd_bus_unrefp</function></funcdef>
  65         <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>void <function>sd_bus_close_unrefp</function></funcdef>
  70         <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef>
  75         <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
  76       </funcprototype>
  77     </funcsynopsis>
  78   </refsynopsisdiv>
  79
  80   <refsect1>
  81     <title>Description</title>
  82
  83     <para><function>sd_bus_new()</function> creates a new bus
  84     object. This object is reference-counted, and will be destroyed
  85     when all references are gone. Initially, the caller of this
  86     function owns the sole reference and the bus object will not be
  87     connected to any bus. To connect it to a bus, make sure
  88     to set an address with
  89     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  90     or a related call, and then start the connection with
  91     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  92
  93     <para>In most cases, it is a better idea to invoke
  94     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  95     <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  96     or related calls instead of the more low-level
  97     <function>sd_bus_new()</function> and
  98     <function>sd_bus_start()</function>. The higher-level calls not
  99     only allocate a bus object but also start the connection to a
 100     well-known bus in a single function invocation.</para>
 101
 102     <para><function>sd_bus_ref()</function> increases the reference
 103     counter of <parameter>bus</parameter> by one.</para>
 104
 105     <para><function>sd_bus_unref()</function> decreases the reference
 106     counter of <parameter>bus</parameter> by one. Once the reference
 107     count has dropped to zero, <parameter>bus</parameter> is destroyed
 108     and cannot be used anymore, so further calls to
 109     <function>sd_bus_ref()</function> or
 110     <function>sd_bus_unref()</function> are illegal.</para>
 111
 112     <para><function>sd_bus_unrefp()</function> is similar to
 113     <function>sd_bus_unref()</function> but takes a pointer to a
 114     pointer to an <type>sd_bus</type> object. This call is useful in
 115     conjunction with GCC's and LLVM's <ulink
 116     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 117     Variable Attribute</ulink>. Note that this function is defined as
 118     inline function. Use a declaration like the following, in order to
 119     allocate a bus object that is freed automatically as the code
 120     block is left:</para>
 121
 122     <programlisting>{
 123   __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
 124   int r;
 125   …
 126   r = sd_bus_default(&amp;bus);
 127   if (r &lt; 0)
 128     fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
 129   …
 130 }</programlisting>
 131
 132     <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
 133     execute no operation if the passed in bus object address is
 134     <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
 135     dereference its argument, which must not be <constant>NULL</constant>, and will
 136     execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
 137     </para>
 138
 139     <para><function>sd_bus_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but
 140     first executes
 141     <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142     ensuring that the connection is terminated before the reference to the connection is dropped and possibly
 143     the object freed.</para>
 144
 145     <para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>,
 146     but first executes
 147     <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well
 148     as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 149     ensuring that any pending messages are synchronously flushed out before the reference to the connection
 150     is dropped and possibly the object freed. This call is particularly useful immediately before exiting
 151     from a program as it ensures that any pending outgoing messages are written out, and unprocessed but
 152     queued incoming messages released before the connection is terminated and released.</para>
 153
 154     <para><function>sd_bus_close_unrefp()</function> is similar to
 155     <function>sd_bus_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable
 156     Attribute, see above. Similarly, <function>sd_bus_flush_close_unrefp()</function> is similar to
 157     <function>sd_bus_flush_close_unref()</function>.</para>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Return Value</title>
 162
 163     <para>On success, <function>sd_bus_new()</function> returns 0 or a
 164     positive integer. On failure, it returns a negative errno-style
 165     error code.</para>
 166
 167     <para><function>sd_bus_ref()</function> always returns the argument.
 168     </para>
 169
 170     <para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return
 171     <constant>NULL</constant>.</para>
 172   </refsect1>
 173
 174   <refsect1>
 175     <title>Errors</title>
 176
 177     <para>Returned errors may indicate the following problems:</para>
 178
 179     <variablelist>
 180       <varlistentry>
 181         <term><constant>-ENOMEM</constant></term>
 182
 183         <listitem><para>Memory allocation failed.</para></listitem>
 184       </varlistentry>
 185     </variablelist>
 186   </refsect1>
 187
 188   <xi:include href="libsystemd-pkgconfig.xml" />
 189
 190   <refsect1>
 191     <title>See Also</title>
 192
 193     <para>
 194       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 196       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 197       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 198       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 199       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 200       <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 201     </para>
 202   </refsect1>
 203
 204 </refentry>