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   This file is part of systemd.
   7
   8   Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_bus_new">
  25
  26   <refentryinfo>
  27     <title>sd_bus_new</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>A monkey with a typewriter</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_bus_new</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_bus_new</refname>
  47     <refname>sd_bus_ref</refname>
  48     <refname>sd_bus_unref</refname>
  49     <refname>sd_bus_unrefp</refname>
  50
  51     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_bus_new</function></funcdef>
  60         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
  65         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
  70         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  71       </funcprototype>
  72
  73       <funcprototype>
  74         <funcdef>void <function>sd_bus_unrefp</function></funcdef>
  75         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  76       </funcprototype>
  77     </funcsynopsis>
  78   </refsynopsisdiv>
  79
  80   <refsect1>
  81     <title>Description</title>
  82
  83     <para><function>sd_bus_new()</function> creates a new bus
  84     object. This object is reference-counted, and will be destroyed
  85     when all references are gone. Initially, the caller of this
  86     function owns the sole reference and the bus object will not be
  87     connected to any bus. To connect it to a bus, make sure
  88     to set an address with
  89     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  90     or a related call, and then start the connection with
  91     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  92
  93     <para>In most cases, it is a better idea to invoke
  94     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  95     <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  96     or related calls instead of the more low-level
  97     <function>sd_bus_new()</function> and
  98     <function>sd_bus_start()</function>. The higher-level calls not
  99     only allocate a bus object but also start the connection to a
 100     well-known bus in a single function invocation.</para>
 101
 102     <para><function>sd_bus_ref()</function> increases the reference
 103     counter of <parameter>bus</parameter> by one.</para>
 104
 105     <para><function>sd_bus_unref()</function> decreases the reference
 106     counter of <parameter>bus</parameter> by one. Once the reference
 107     count has dropped to zero, <parameter>bus</parameter> is destroyed
 108     and cannot be used anymore, so further calls to
 109     <function>sd_bus_ref()</function> or
 110     <function>sd_bus_unref()</function> are illegal.</para>
 111
 112     <para><function>sd_bus_unrefp()</function> is similar to
 113     <function>sd_bus_unref()</function> but takes a pointer to a
 114     pointer to an <type>sd_bus</type> object. This call is useful in
 115     conjunction with GCC's and LLVM's <ulink
 116     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 117     Variable Attribute</ulink>. Note that this function is defined as
 118     inline function. Use a declaration like the following, in order to
 119     allocate a bus object that is freed automatically as the code
 120     block is left:</para>
 121
 122     <programlisting>{
 123         __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
 124         int r;
 125         …
 126         r = sd_bus_default(&amp;bus);
 127         if (r &lt; 0)
 128                 fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
 129         …
 130 }</programlisting>
 131
 132     <para><function>sd_bus_ref()</function>,
 133     <function>sd_bus_unref()</function> and
 134     <function>sd_bus_unrefp()</function> execute no operation if the
 135     passed in bus object is <constant>NULL</constant>.</para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Return Value</title>
 140
 141     <para>On success, <function>sd_bus_new()</function> returns 0 or a
 142     positive integer. On failure, it returns a negative errno-style
 143     error code.</para>
 144
 145     <para><function>sd_bus_ref()</function> always returns the argument.
 146     </para>
 147
 148     <para><function>sd_bus_unref()</function> always returns
 149     <constant>NULL</constant>.</para>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Errors</title>
 154
 155     <para>Returned errors may indicate the following problems:</para>
 156
 157     <variablelist>
 158       <varlistentry>
 159         <term><constant>-ENOMEM</constant></term>
 160
 161         <listitem><para>Memory allocation failed.</para></listitem>
 162       </varlistentry>
 163     </variablelist>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Notes</title>
 168
 169     <para><function>sd_bus_new()</function> and other functions
 170     described here are available as a shared library, which can be
 171     compiled and linked to with the
 172     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 173     file.</para>
 174   </refsect1>
 175
 176   <refsect1>
 177     <title>See Also</title>
 178
 179     <para>
 180       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 186     </para>
 187   </refsect1>
 188
 189 </refentry>