man/sd_bus_open_system_machine.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_default</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21
  22   <span style="float:right">systemd 221</span><hr><div class="refentry"><a name="sd_bus_default"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_default, sd_bus_default_user, sd_bus_default_system, sd_bus_open, sd_bus_open_user, sd_bus_open_system, sd_bus_open_system_remote, sd_bus_open_system_machine — Acquire a connection to a 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_default</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_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><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</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_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>sd_bus **<var class="pdparam">bus</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">host</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_machine</b>(</code></td><td>sd_bus **<var class="pdparam">bus</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">machine</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm47392292488608"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_bus_default()</code> acquires a bus
  23     connection object to the user bus when invoked in user context or
  24     to the system bus otherwise. The connection object is associated
  25     to the calling thread. Each time the function is invoked from the
  26     same thread the same object is returned, but its reference count
  27     increased by one, as long as at least one reference is kept. When
  28     the last reference to the connection is dropped (using the
  29     <code class="function">sd_bus_unref()</code> call), the connection is
  30     terminated. Note that the connection is not automatically
  31     terminated when the associated thread ends. It is important to
  32     drop the last reference to the bus connection explicitly before
  33     the thread ends or otherwise the connection will be leaked.</p><p><code class="function">sd_bus_default_user()</code> returns a user
  34     bus connection object associated to the calling thread.
  35     <code class="function">sd_bus_default_system()</code> is similar, but
  36     connects to the system bus.</p><p><code class="function">sd_bus_open()</code> creates a new,
  37     independent bus connection to the user bus when invoked in user
  38     context or the system bus
  39     otherwise. <code class="function">sd_bus_open_user()</code> is similar, but
  40     connects only to the user bus.
  41     <code class="function">sd_bus_open_system()</code> does the same, but
  42     connects to the system bus. In contrast to
  43     <code class="function">sd_bus_default()</code>,
  44     <code class="function">sd_bus_default_user()</code>,
  45     <code class="function">sd_bus_default_system()</code> these calls return
  46     new, independent connection objects that are not associated with
  47     the invoking thread and are not shared between multiple
  48     invocations. It is recommended to share connections per thread to
  49     efficiently make use the available resources. Thus, it is
  50     recommended to use <code class="function">sd_bus_default()</code>,
  51     <code class="function">sd_bus_default_user()</code>,
  52     <code class="function">sd_bus_default_system()</code> to connect to the
  53     user or system buses.</p><p>If the <code class="varname">$DBUS_SESSION_BUS_ADDRESS</code> environment
  54     variable is set
  55     (cf. <a href="http://man7.org/linux/man-pages/man7/environ.7.html"><span class="citerefentry"><span class="refentrytitle">environ</span>(7)</span></a>),
  56     it will be used as the address of the user bus. This variable can
  57     contain multiple addresses separated by "<code class="literal">;</code>". If
  58     this variable is not set, a suitable default for the default user
  59     D-Bus instance will be used.</p><p>If the <code class="varname">$DBUS_SYSTEM_BUS_ADDRESS</code>
  60     environment variable is set, it will be used as the address of the
  61     system bus. This variable uses the same syntax as
  62     <code class="varname">$DBUS_SESSION_BUS_ADDRESS</code>. If this variable is
  63     not set, a suitable default for the default system D-Bus instance
  64     will be used.</p><p><code class="function">sd_bus_open_system_remote()</code> connects to
  65     the system bus on the specified <em class="parameter"><code>host</code></em> using
  66     SSH. <em class="parameter"><code>host</code></em> consists of an optional user name
  67     followed by the "<code class="literal">@</code>" symbol, and the hostname.
  68     </p><p><code class="function">sd_bus_open_system_container()</code> connects
  69     to the system bus in the specified <em class="parameter"><code>machine</code></em>,
  70     where <em class="parameter"><code>machine</code></em> is the name of a local
  71     container.  See
  72     <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
  73     for more information about "machines".</p></div><div class="refsect1"><a name="idm47392292467584"></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
  74     integer. On failure, these calls return a negative
  75     errno-style error code.</p></div><div class="refsect1"><a name="idm47392292466288"></a><h2 id="Reference ownership">Reference ownership<a class="headerlink" title="Permalink to this headline" href="#Reference%20ownership">¶</a></h2><p>The functions <code class="function">sd_bus_open_user()</code>,
  76     <code class="function">sd_bus_open()</code>,
  77     <code class="function">sd_bus_open_system()</code>,
  78     <code class="function">sd_bus_open_system_remote()</code>, and
  79     <code class="function">sd_bus_open_system_machine()</code> return a new
  80     object and the caller owns the sole reference. When not needed
  81     anymore, this reference should be destroyed with
  82     <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>.
  83     </p><p>The functions <code class="function">sd_bus_default()</code>,
  84     <code class="function">sd_bus_default_user()</code> and
  85     <code class="function">sd_bus_default_system()</code> do not necessarily
  86     create a new object, but increase the connection reference by
  87     one. Use
  88     <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>
  89     to drop the reference.</p></div><div class="refsect1"><a name="idm47392292457952"></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"><dl class="variablelist"><dt id="-EINVAL"><span class="term"><code class="constant">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL">¶</a></dt><dd><p>The specified parameters are invalid.</p></dd><dt id="-ENOMEM"><span class="term"><code class="constant">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM">¶</a></dt><dd><p>Memory allocation failed.</p></dd><dt id="-ESOCKTNOSUPPORT"><span class="term"><code class="constant">-ESOCKTNOSUPPORT</code></span><a class="headerlink" title="Permalink to this term" href="#-ESOCKTNOSUPPORT">¶</a></dt><dd><p>The protocol version required to connect to the selected bus is not supported.</p></dd></dl></div><p>In addition, any further connection-related errors may be
  90     by returned. See <a href="sd_bus_send.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_send</span>(3)</span></a>.</p></div><div class="refsect1"><a name="idm47392292450944"></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 the other
  91     functions described here are available as a shared library, which
  92     can be compiled and linked to with the
  93     <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  94     file.</p></div><div class="refsect1"><a name="idm47392292447760"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  95       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  96       <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
  97       <a href="sd_bus_new.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_new</span>(3)</span></a>,
  98       <a href="sd_bus_ref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_ref</span>(3)</span></a>,
  99       <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>,
 100       <a href="http://linux.die.net/man/1/ssh"><span class="citerefentry"><span class="refentrytitle">ssh</span>(1)</span></a>,
 101       <a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>,
 102       <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
 103     </p></div></div></body></html>