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