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 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2014 Zbigniew Jędrzejewski-Szmek
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id=
"sd_bus_default" conditional=
"ENABLE_KDBUS">
30 <title>sd_bus_default
</title>
31 <productname>systemd
</productname>
35 <contrib>A monkey with a typewriter
</contrib>
36 <firstname>Zbigniew
</firstname>
37 <surname>Jędrzejewski-Szmek
</surname>
38 <email>zbyszek@in.waw.pl
</email>
44 <refentrytitle>sd_bus_default
</refentrytitle>
45 <manvolnum>3</manvolnum>
49 <refname>sd_bus_default
</refname>
50 <refname>sd_bus_default_user
</refname>
51 <refname>sd_bus_default_system
</refname>
53 <refname>sd_bus_open
</refname>
54 <refname>sd_bus_open_user
</refname>
55 <refname>sd_bus_open_system
</refname>
56 <refname>sd_bus_open_system_remote
</refname>
57 <refname>sd_bus_open_system_machine
</refname>
59 <refpurpose>Acquire a connection to a system or user bus
</refpurpose>
64 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
67 <funcdef>int
<function>sd_bus_default
</function></funcdef>
68 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
72 <funcdef>int
<function>sd_bus_default_user
</function></funcdef>
73 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
77 <funcdef>int
<function>sd_bus_default_system
</function></funcdef>
78 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
82 <funcdef>int
<function>sd_bus_open
</function></funcdef>
83 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
87 <funcdef>int
<function>sd_bus_open_user
</function></funcdef>
88 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
92 <funcdef>int
<function>sd_bus_open_system
</function></funcdef>
93 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
97 <funcdef>int
<function>sd_bus_open_system_remote
</function></funcdef>
98 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
99 <paramdef>const char *
<parameter>host
</parameter></paramdef>
103 <funcdef>int
<function>sd_bus_open_system_machine
</function></funcdef>
104 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
105 <paramdef>const char *
<parameter>machine
</parameter></paramdef>
112 <title>Description
</title>
114 <para><function>sd_bus_default()
</function> acquires a bus
115 connection object to the user bus when invoked in user context or
116 to the system bus otherwise. The connection object is associated
117 to the calling thread. Each time the function is invoked from the
118 same thread the same object is returned, but its reference count
119 increased by one, as long as at least one reference is kept. When
120 the last reference to the connection is dropped (using the
121 <function>sd_bus_unref()
</function> call), the connection is
122 terminated. Note that the connection is not automatically
123 terminated when the associated thread ends. It is important to
124 drop the last reference to the bus connection explicitly before
125 the thread ends or otherwise the connection will be leaked.
</para>
127 <para><function>sd_bus_default_user()
</function> returns a user
128 bus connection object associated to the calling thread.
129 <function>sd_bus_default_system()
</function> is similar, but
130 connects to the system bus.
</para>
132 <para><function>sd_bus_open()
</function> creates a new,
133 independent bus connection to the user bus when invoked in user
134 context or the system bus
135 otherwise.
<function>sd_bus_open_user()
</function> is similar, but
136 connects only to the user bus.
137 <function>sd_bus_open_system()
</function> does the same, but
138 connects to the system bus. In contrast to
139 <function>sd_bus_default()
</function>,
140 <function>sd_bus_default_user()
</function>,
141 <function>sd_bus_default_system()
</function> these calls return
142 new, independent connection objects that are not associated with
143 the invoking thread and are not shared between multiple
144 invocations. It is recommended to share connections per thread to
145 efficiently make use the available resources. Thus, it is
146 recommended to use
<function>sd_bus_default()
</function>,
147 <function>sd_bus_default_user()
</function>,
148 <function>sd_bus_default_system()
</function> to connect to the
149 user or system buses.
</para>
151 <para>If the
<varname>$DBUS_SESSION_BUS_ADDRESS
</varname> environment
153 (cf.
<citerefentry project='man-pages'
><refentrytitle>environ
</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
154 it will be used as the address of the user bus. This variable can
155 contain multiple addresses separated by
<literal>;
</literal>. If
156 this variable is not set, a suitable default for the default user
157 D-Bus instance will be used.
</para>
159 <para>If the
<varname>$DBUS_SYSTEM_BUS_ADDRESS
</varname>
160 environment variable is set, it will be used as the address of the
161 system bus. This variable uses the same syntax as
162 <varname>$DBUS_SESSION_BUS_ADDRESS
</varname>. If this variable is
163 not set, a suitable default for the default system D-Bus instance
166 <para><function>sd_bus_open_system_remote()
</function> connects to
167 the system bus on the specified
<parameter>host
</parameter> using
168 SSH.
<parameter>host
</parameter> consists of an optional user name
169 followed by the
<literal>@
</literal> symbol, and the hostname.
172 <para><function>sd_bus_open_system_container()
</function> connects
173 to the system bus in the specified
<parameter>machine
</parameter>,
174 where
<parameter>machine
</parameter> is the name of a local
176 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
177 for more information about
"machines".
</para>
182 <title>Return Value
</title>
184 <para>On success, these calls return
0 or a positive
185 integer. On failure, these calls return a negative
186 errno-style error code.
</para>
190 <title>Reference ownership
</title>
191 <para>The functions
<function>sd_bus_open_user()
</function>,
192 <function>sd_bus_open()
</function>,
193 <function>sd_bus_open_system()
</function>,
194 <function>sd_bus_open_system_remote()
</function>, and
195 <function>sd_bus_open_system_machine()
</function> return a new
196 object and the caller owns the sole reference. When not needed
197 anymore, this reference should be destroyed with
198 <citerefentry><refentrytitle>sd_bus_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
201 <para>The functions
<function>sd_bus_default()
</function>,
202 <function>sd_bus_default_user()
</function> and
203 <function>sd_bus_default_system()
</function> do not necessarily
204 create a new object, but increase the connection reference by
206 <citerefentry><refentrytitle>sd_bus_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
207 to drop the reference.
</para>
211 <title>Errors
</title>
213 <para>Returned errors may indicate the following problems:
</para>
218 <term><constant>-EINVAL
</constant></term>
220 <listitem><para>The specified parameters are invalid.
</para></listitem>
224 <term><constant>-ENOMEM
</constant></term>
226 <listitem><para>Memory allocation failed.
</para></listitem>
230 <term><constant>-ESOCKTNOSUPPORT
</constant></term>
232 <listitem><para>The protocol version required to connect to the selected bus is not supported.
</para></listitem>
236 <para>In addition, any further connection-related errors may be
237 by returned. See
<citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
243 <para><function>sd_bus_open_user()
</function> and the other
244 functions described here are available as a shared library, which
245 can be compiled and linked to with the
246 <constant>libsystemd
</constant> <citerefentry
247 project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
252 <title>See Also
</title>
255 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
256 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
257 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
258 <citerefentry><refentrytitle>sd_bus_ref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>sd_bus_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
260 <citerefentry project='die-net'
><refentrytitle>ssh
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>