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>bus</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>,
 109     <function>sd_bus_unref()</function> and
 110     <function>sd_bus_unrefp()</function> execute no operation if the
 111     passed in bus object is <constant>NULL</constant>.</para>
 112   </refsect1>
 113
 114   <refsect1>
 115     <title>Return Value</title>
 116
 117     <para>On success, <function>sd_bus_new()</function> returns 0 or a
 118     positive integer. On failure, it returns a negative errno-style
 119     error code.</para>
 120
 121     <para><function>sd_bus_ref()</function> always returns the argument.
 122     </para>
 123
 124     <para><function>sd_bus_unref()</function> always returns
 125     <constant>NULL</constant>.</para>
 126   </refsect1>
 127
 128   <refsect1>
 129     <title>Errors</title>
 130
 131     <para>Returned errors may indicate the following problems:</para>
 132
 133     <variablelist>
 134       <varlistentry>
 135         <term><constant>-ENOMEM</constant></term>
 136
 137         <listitem><para>Memory allocation failed.</para></listitem>
 138       </varlistentry>
 139     </variablelist>
 140   </refsect1>
 141
 142   <xi:include href="libsystemd-pkgconfig.xml" />
 143
 144   <refsect1>
 145     <title>See Also</title>
 146
 147     <para>
 148       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 154     </para>
 155   </refsect1>
 156
 157 </refentry>