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