1 <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>
11 background-color: #c60f0f;
15 h1:hover
> a.headerlink, h2:hover
> a.headerlink, h3:hover
> a.headerlink, dt:hover
> a.headerlink {
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 <a href=
"../libudev/index.html">libudev
</a>·
22 <a href=
"../libudev/index.html">gudev
</a><span style=
"float:right">systemd
217</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
<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_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=
"idm214194775536"></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 object and opens a connection to the user bus.
24 <code class=
"function">sd_bus_open_system()
</code> does the same, but
25 connects to the system bus.
</p><p>If the
<code class=
"varname">$DBUS_SESSION_BUS_ADDRESS
</code> environment
27 (cf.
<a href=
"http://man7.org/linux/man-pages/man7/environ.7.html"><span class=
"citerefentry"><span class=
"refentrytitle">environ
</span>(
7)
</span></a>),
28 it will be used as the address of the user bus. This variable can
29 contain multiple addresses separated by
"<code class="literal
">;</code>". If
30 this variable is not set, a suitable default for the default user
31 D-Bus instance will be used.
</p><p>If the
<code class=
"varname">$DBUS_SYSTEM_BUS_ADDRESS
</code> environment
32 variable is set, it will be used as the address of the system
33 bus. This variable uses the same syntax as
34 <code class=
"varname">$DBUS_SESSION_BUS_ADDRESS
</code>/. If this variable is
35 not set, a suitable default for the default system D-Bus instance
36 will be used.
</p><p><code class=
"function">sd_bus_open_system_remote()
</code> connects to
37 the system bus on the specified
<em class=
"parameter"><code>host
</code></em> using
38 SSH.
<em class=
"parameter"><code>host
</code></em> consists of an optional user name
39 followed by the
"<code class="literal
">@</code>" symbol, and the hostname.
40 </p><p><code class=
"function">sd_bus_open_system_remote()
</code> connects to
41 the system bus in the specified
<em class=
"parameter"><code>machine
</code></em>,
42 where
<em class=
"parameter"><code>machine
</code></em> is the name of a container.
44 <a href=
"machinectl.html"><span class=
"citerefentry"><span class=
"refentrytitle">machinectl
</span>(
1)
</span></a>
45 for more information about
"machines".
</p><p><code class=
"function">sd_bus_default_user()
</code> returns a bus
46 object connected to the user bus. Each thread has its own object, but it
47 may be passed around. It is created on the first invocation of
48 <code class=
"function">sd_bus_default_user()
</code>, and subsequent
49 invocations returns a reference to the same object.
</p><p><code class=
"function">sd_bus_default_system()
</code> is similar to
50 <code class=
"function">sd_bus_default_user()
</code>, but connects to the
51 system bus.
</p></div><div class=
"refsect1"><a name=
"idm214194751488"></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
53 errno-style error code.
</p></div><div class=
"refsect1"><a name=
"idm214194750160"></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 <code class=
"function">sd_bus_open_system()
</code>,
55 <code class=
"function">sd_bus_open_system_remote()
</code>, and
56 <code class=
"function">sd_bus_open_system_machine()
</code> return a new
57 object and the caller owns the sole reference. When not needed
58 anymore, this reference should be destroyed with
59 <a href=
"sd_bus_unref.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_unref
</span>(
3)
</span></a>.
60 </p><p>The functions
<code class=
"function">sd_bus_default_user()
</code> and
61 <code class=
"function">sd_bus_default_system()
</code> do not create a new
62 reference.
</p></div><div class=
"refsect1"><a name=
"idm214194743200"></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 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=
"constant">-EINVAL
</code></span><a class=
"headerlink" title=
"Permalink to this term" href=
"#-EINVAL">¶
</a></dt><dd><p>Specified parameter is invalid
64 (
<code class=
"constant">NULL
</code> in case of output
65 parameters).
</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></dl></div></div><div class=
"refsect1"><a name=
"idm214194737008"></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 described here are available as a shared library, which can be
67 compiled and linked to with the
68 <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>
69 file.
</p></div><div class=
"refsect1"><a name=
"idm214194733568"></a><h2 id=
"See Also">See Also
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#See%20Also">¶
</a></h2><p>
70 <a href=
"systemd.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd
</span>(
1)
</span></a>,
71 <a href=
"sd-bus.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd-bus
</span>(
3)
</span></a>,
72 <a href=
"sd_bus_new.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_new
</span>(
3)
</span></a>,
73 <a href=
"sd_bus_ref.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_ref
</span>(
3)
</span></a>,
74 <a href=
"sd_bus_unref.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_unref
</span>(
3)
</span></a>,
75 <a href=
"ssh.html"><span class=
"citerefentry"><span class=
"refentrytitle">ssh
</span>(
1)
</span></a>,
76 <a href=
"systemd-machined.service.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd-machined.service
</span>(
8)
</span></a>,
77 <a href=
"machinectl.html"><span class=
"citerefentry"><span class=
"refentrytitle">machinectl
</span>(
1)
</span></a>
78 </p></div></div></body></html>