1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
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
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
<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>
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>·
<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 <systemd/sd-bus.h></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
connection object to the user bus when invoked in user context or
to the system bus otherwise. The connection object is associated
to the calling thread. Each time the function is invoked from the
same thread the same object is returned, but its reference count
increased by one, as long as at least one reference is kept. When
the last reference to the connection is dropped (using the
<code class="function">sd_bus_unref()</code> call), the connection is
terminated. Note that the connection is not automatically
terminated when the associated thread ends. It is important to
drop the last reference to the bus connection explicitly before
the thread ends or otherwise the connection will be leaked.</p><p><code class="function">sd_bus_default_user()</code> returns a user
bus connection object associated to the calling thread.
<code class="function">sd_bus_default_system()</code> is similar, but
connects to the system bus.</p><p><code class="function">sd_bus_open()</code> creates a new,
independent bus connection to the user bus when invoked in user
context or the system bus
otherwise. <code class="function">sd_bus_open_user()</code> is similar, but
connects only to the user bus.
<code class="function">sd_bus_open_system()</code> does the same, but
connects to the system bus. In contrast to
<code class="function">sd_bus_default()</code>,
<code class="function">sd_bus_default_user()</code>,
<code class="function">sd_bus_default_system()</code> these calls return
new, independent connection objects that are not associated with
the invoking thread and are not shared between multiple
invocations. It is recommended to share connections per thread to
efficiently make use the available resources. Thus, it is
recommended to use <code class="function">sd_bus_default()</code>,
<code class="function">sd_bus_default_user()</code>,
<code class="function">sd_bus_default_system()</code> to connect to the
user or system buses.</p><p>If the <code class="varname">$DBUS_SESSION_BUS_ADDRESS</code> environment
variable is set
(cf. <a href="http://man7.org/linux/man-pages/man7/environ.7.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_container()</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 local
container. See
<a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
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
integer. On failure, these calls return a negative
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>,
<code class="function">sd_bus_open()</code>,
<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()</code>,
<code class="function">sd_bus_default_user()</code> and
<code class="function">sd_bus_default_system()</code> do not necessarily
create a new object, but increase the connection reference by
one. Use
<a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>
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
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
functions described here are available as a shared library, which
can be compiled and linked to with the
<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>
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>
<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="http://linux.die.net/man/1/ssh"><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>
|
