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