2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_bus_start"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_bus_start
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_bus_start
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_bus_start
</refname>
22 <refpurpose>Initiate a bus connection to the D-bus broker daemon
28 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
31 <funcdef>int
<function>sd_bus_start
</function></funcdef>
32 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
38 <title>Description
</title>
40 <para><function>sd_bus_start()
</function> connects an existing bus connection object to the D-Bus
41 broker daemon, usually
42 <citerefentry project='die-net'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
44 <citerefentry project='mankier'
><refentrytitle>dbus-broker
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
45 The mechanism to use for the connection must be configured before the call to
46 <function>sd_bus_start()
</function>, using one of
47 <citerefentry><refentrytitle>sd_bus_set_address
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
48 <citerefentry><refentrytitle>sd_bus_set_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or
49 <citerefentry><refentrytitle>sd_bus_set_exec
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
50 <function>sd_bus_start()
</function> will open the connection socket or spawn the executable as
51 needed, and asynchronously start a
<function>org.freedesktop.DBus.Hello()
</function> call. The
52 answer to the Hello call will be processed later from
53 <citerefentry><refentrytitle>sd_bus_process
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
54 opening of the connection or queuing of the asynchronous call fail, the connection will be closed with
55 <citerefentry><refentrytitle>sd_bus_close
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
57 <para>In most cases, it is better to use
58 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
59 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
60 or related calls instead of the more low-level
<function>sd_bus_new()
</function> and
61 <function>sd_bus_start()
</function>. The higher-level functions not only allocate a bus object but also
62 start the connection to a well-known bus in a single function call.
</para>
66 <title>Return Value
</title>
68 <para>On success, this function returns a non-negative integer. On failure, it returns a negative
69 errno-style error code.
</para>
71 <refsect2 id='errors'
>
76 <term><constant>-EINVAL
</constant></term>
78 <listitem><para>The input parameter
<parameter>bus
</parameter> is
<constant>NULL
</constant>.
83 <term><constant>-ENOPKG
</constant></term>
85 <listitem><para>Bus object
<parameter>bus
</parameter> could not be resolved.
</para>
90 <term><constant>-EPERM
</constant></term>
92 <listitem><para>The input parameter
<parameter>bus
</parameter> is in a wrong state
93 (
<function>sd_bus_start()
</function> may only be called once on a newly-created bus object).
</para>
98 <term><constant>-ECHILD
</constant></term>
100 <listitem><para>The bus object
<parameter>bus
</parameter> was created in a different
106 <para>In addition, other connection-related errors may be returned. See
107 <citerefentry><refentrytitle>sd_bus_send
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
111 <xi:include href=
"libsystemd-pkgconfig.xml" />
114 <title>See Also
</title>
117 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
118 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
119 <citerefentry><refentrytitle>sd_bus_default
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
120 <citerefentry><refentrytitle>sd_bus_call_async
</refentrytitle><manvolnum>3</manvolnum></citerefentry>