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
  27     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcprototype>
  35         <funcdef>int <function>sd_bus_new</function></funcdef>
  36         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
  41         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  42       </funcprototype>
  43
  44       <funcprototype>
  45         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
  46         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  47       </funcprototype>
  48
  49       <funcprototype>
  50         <funcdef>void <function>sd_bus_unrefp</function></funcdef>
  51         <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
  52       </funcprototype>
  53     </funcsynopsis>
  54   </refsynopsisdiv>
  55
  56   <refsect1>
  57     <title>Description</title>
  58
  59     <para><function>sd_bus_new()</function> creates a new bus
  60     object. This object is reference-counted, and will be destroyed
  61     when all references are gone. Initially, the caller of this
  62     function owns the sole reference and the bus object will not be
  63     connected to any bus. To connect it to a bus, make sure
  64     to set an address with
  65     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  66     or a related call, and then start the connection with
  67     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  68
  69     <para>In most cases, it is a better idea to invoke
  70     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  71     <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  72     or related calls instead of the more low-level
  73     <function>sd_bus_new()</function> and
  74     <function>sd_bus_start()</function>. The higher-level calls not
  75     only allocate a bus object but also start the connection to a
  76     well-known bus in a single function invocation.</para>
  77
  78     <para><function>sd_bus_ref()</function> increases the reference
  79     counter of <parameter>bus</parameter> by one.</para>
  80
  81     <para><function>sd_bus_unref()</function> decreases the reference
  82     counter of <parameter>bus</parameter> by one. Once the reference
  83     count has dropped to zero, <parameter>bus</parameter> is destroyed
  84     and cannot be used anymore, so further calls to
  85     <function>sd_bus_ref()</function> or
  86     <function>sd_bus_unref()</function> are illegal.</para>
  87
  88     <para><function>sd_bus_unrefp()</function> is similar to
  89     <function>sd_bus_unref()</function> but takes a pointer to a
  90     pointer to an <type>sd_bus</type> object. This call is useful in
  91     conjunction with GCC's and LLVM's <ulink
  92     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
  93     Variable Attribute</ulink>. Note that this function is defined as
  94     inline function. Use a declaration like the following, in order to
  95     allocate a bus object that is freed automatically as the code
  96     block is left:</para>
  97
  98     <programlisting>{
  99   __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
 100   int r;
 101   …
 102   r = sd_bus_default(&amp;bus);
 103   if (r &lt; 0)
 104     fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
 105   …
 106 }</programlisting>
 107
 108     <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
 109     execute no operation if the passed in bus object address is
 110     <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
 111     dereference its argument, which must not be <constant>NULL</constant>, and will
 112     execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
 113     </para>
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>Return Value</title>
 118
 119     <para>On success, <function>sd_bus_new()</function> returns 0 or a
 120     positive integer. On failure, it returns a negative errno-style
 121     error code.</para>
 122
 123     <para><function>sd_bus_ref()</function> always returns the argument.
 124     </para>
 125
 126     <para><function>sd_bus_unref()</function> always returns
 127     <constant>NULL</constant>.</para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Errors</title>
 132
 133     <para>Returned errors may indicate the following problems:</para>
 134
 135     <variablelist>
 136       <varlistentry>
 137         <term><constant>-ENOMEM</constant></term>
 138
 139         <listitem><para>Memory allocation failed.</para></listitem>
 140       </varlistentry>
 141     </variablelist>
 142   </refsect1>
 143
 144   <xi:include href="libsystemd-pkgconfig.xml" />
 145
 146   <refsect1>
 147     <title>See Also</title>
 148
 149     <para>
 150       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 156     </para>
 157   </refsect1>
 158
 159 </refentry>