sd_bus_open_user.html 9.62 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_open_user</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_bus_open_user"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_open_user, sd_bus_open_system, sd_bus_open_system_remote, sd_bus_open_system_container, sd_bus_default_user, sd_bus_default_system — Open a connection to the system or user bus</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-bus.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_open_user</b>(</code></td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_open_system</b>(</code></td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_open_system_remote</b>(</code></td><td>const char *<var class="pdparam">host</var>, </td></tr><tr><td> </td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_open_system_container</b>(</code></td><td>const char *<var class="pdparam">machine</var>, </td></tr><tr><td> </td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_default_user</b>(</code></td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_default_system</b>(</code></td><td>sd_bus **<var class="pdparam">bus</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214201032336"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p><code class="function">sd_bus_open_user()</code> creates a new bus
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
    object and opens a connection to the user bus.
    <code class="function">sd_bus_open_system()</code> does the same, but
    connects to the system bus.</p><p>If the <code class="varname">$DBUS_SESSION_BUS_ADDRESS</code> environment
    variable is set
    (cf. <a href="environ.html"><span class="citerefentry"><span class="refentrytitle">environ</span>(7)</span></a>),
    it will be used as the address of the user bus. This variable can
    contain multiple addresses separated by "<code class="literal">;</code>". If
    this variable is not set, a suitable default for the default user
    D-Bus instance will be used.</p><p>If the <code class="varname">$DBUS_SYSTEM_BUS_ADDRESS</code> environment
    variable is set, it will be used as the address of the system
    bus. This variable uses the same syntax as
    <code class="varname">$DBUS_SESSION_BUS_ADDRESS</code>/. If this variable is
    not set, a suitable default for the default system D-Bus instance
    will be used.</p><p><code class="function">sd_bus_open_system_remote()</code> connects to
    the system bus on the specified <em class="parameter"><code>host</code></em> using
    SSH. <em class="parameter"><code>host</code></em> consists of an optional user name
    followed by the "<code class="literal">@</code>" symbol, and the hostname.
    </p><p><code class="function">sd_bus_open_system_remote()</code> connects to
    the system bus in the specified <em class="parameter"><code>machine</code></em>,
    where <em class="parameter"><code>machine</code></em> is the name of a container.
    See
    <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
    for more information about "machines".</p><p><code class="function">sd_bus_default_user()</code> returns a bus
    object connected to the user bus. Each thread has its own object, but it
    may be passed around. It is created on the first invocation of
    <code class="function">sd_bus_default_user()</code>, and subsequent
    invocations returns a reference to the same object.</p><p><code class="function">sd_bus_default_system()</code> is similar to
    <code class="function">sd_bus_default_user()</code>, but connects to the
Michael Biebl's avatar
Michael Biebl committed
51
    system bus.</p></div><div class="refsect1"><a name="idm214201008656"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>On success, these calls return 0 or a positive
52
    integer. On failure, these calls return a negative
Michael Biebl's avatar
Michael Biebl committed
53
    errno-style error code.</p></div><div class="refsect1"><a name="idm214201007328"></a><h2 id="Reference ownership">Reference ownership<a class="headerlink" title="Permalink to this headline" href="#Reference%20ownership"></a></h2><p>Functions <code class="function">sd_bus_open_user()</code>,
54 55 56 57 58 59 60 61
    <code class="function">sd_bus_open_system()</code>,
    <code class="function">sd_bus_open_system_remote()</code>, and
    <code class="function">sd_bus_open_system_machine()</code> return a new
    object and the caller owns the sole reference. When not needed
    anymore, this reference should be destroyed with
    <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>.
    </p><p>The functions <code class="function">sd_bus_default_user()</code> and
    <code class="function">sd_bus_default_system()</code> do not create a new
Michael Biebl's avatar
Michael Biebl committed
62
    reference.</p></div><div class="refsect1"><a name="idm214201000368"></a><h2 id="Errors">Errors<a class="headerlink" title="Permalink to this headline" href="#Errors"></a></h2><p>Returned errors may indicate the following problems:</p><div class="variablelist"><p>In addition, any further connection-related errors may be
63 64
      by returned. See <a href="sd_bus_send.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_send</span>(3)</span></a>.</p><dl class="variablelist"><dt id="-EINVAL"><span class="term"><code class="varname">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL"></a></dt><dd><p>Specified parameter is invalid
        (<code class="constant">NULL</code> in case of output
Michael Biebl's avatar
Michael Biebl committed
65
        parameters).</p></dd><dt id="-ENOMEM"><span class="term"><code class="varname">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM"></a></dt><dd><p>Memory allocation failed.</p></dd></dl></div></div><div class="refsect1"><a name="idm214200994176"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p><code class="function">sd_bus_open_user()</code> and other functions
66 67 68
    described here are available as a shared library, which can be
    compiled and linked to with the
    <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
69
    file.</p></div><div class="refsect1"><a name="idm214200991008"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
70 71 72 73 74 75 76 77 78
      <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
      <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
      <a href="sd_bus_new.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_new</span>(3)</span></a>,
      <a href="sd_bus_ref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_ref</span>(3)</span></a>,
      <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>,
      <a href="ssh.html"><span class="citerefentry"><span class="refentrytitle">ssh</span>(1)</span></a>,
      <a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>,
      <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
    </p></div></div></body></html>