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   Copyright © 2014 Zbigniew Jędrzejewski-Szmek
   9 -->
  10
  11 <refentry id="sd_bus_new" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_bus_new</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_new</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_new</refname>
  25     <refname>sd_bus_ref</refname>
  26     <refname>sd_bus_unref</refname>
  27     <refname>sd_bus_unrefp</refname>
  28
  29     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  30   </refnamediv>
  31
  32   <refsynopsisdiv>
  33     <funcsynopsis>
  34       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  35
  36       <funcprototype>
  37         <funcdef>int <function>sd_bus_new</function></funcdef>
  38         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  39       </funcprototype>
  40
  41       <funcprototype>
  42         <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
  43         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
  48         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>void <function>sd_bus_unrefp</function></funcdef>
  53         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  54       </funcprototype>
  55     </funcsynopsis>
  56   </refsynopsisdiv>
  57
  58   <refsect1>
  59     <title>Description</title>
  60
  61     <para><function>sd_bus_new()</function> creates a new bus
  62     object. This object is reference-counted, and will be destroyed
  63     when all references are gone. Initially, the caller of this
  64     function owns the sole reference and the bus object will not be
  65     connected to any bus. To connect it to a bus, make sure
  66     to set an address with
  67     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  68     or a related call, and then start the connection with
  69     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  70
  71     <para>In most cases, it is a better idea to invoke
  72     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  73     <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  74     or related calls instead of the more low-level
  75     <function>sd_bus_new()</function> and
  76     <function>sd_bus_start()</function>. The higher-level calls not
  77     only allocate a bus object but also start the connection to a
  78     well-known bus in a single function invocation.</para>
  79
  80     <para><function>sd_bus_ref()</function> increases the reference
  81     counter of <parameter>bus</parameter> by one.</para>
  82
  83     <para><function>sd_bus_unref()</function> decreases the reference
  84     counter of <parameter>bus</parameter> by one. Once the reference
  85     count has dropped to zero, <parameter>bus</parameter> is destroyed
  86     and cannot be used anymore, so further calls to
  87     <function>sd_bus_ref()</function> or
  88     <function>sd_bus_unref()</function> are illegal.</para>
  89
  90     <para><function>sd_bus_unrefp()</function> is similar to
  91     <function>sd_bus_unref()</function> but takes a pointer to a
  92     pointer to an <type>sd_bus</type> object. This call is useful in
  93     conjunction with GCC's and LLVM's <ulink
  94     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
  95     Variable Attribute</ulink>. Note that this function is defined as
  96     inline function. Use a declaration like the following, in order to
  97     allocate a bus object that is freed automatically as the code
  98     block is left:</para>
  99
 100     <programlisting>{
 101         __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
 102         int r;
 103         …
 104         r = sd_bus_default(&amp;bus);
 105         if (r &lt; 0)
 106                 fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
 107         …
 108 }</programlisting>
 109
 110     <para><function>sd_bus_ref()</function>,
 111     <function>sd_bus_unref()</function> and
 112     <function>sd_bus_unrefp()</function> execute no operation if the
 113     passed in bus object is <constant>NULL</constant>.</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="libelogind-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>