5484N/A<?xml version='1.0'?> <!--*-nxml-*-->

5484N/A<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

5484N/A"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

5484N/A

5484N/A

5484N/A<refentry id="sd_bus_open_user" conditional="ENABLE_KDBUS">

5484N/A

5484N/A <refentryinfo>

5484N/A <title>sd_bus_open_user</title>

5484N/A <productname>systemd</productname>

6784N/A

5484N/A <authorgroup>

5484N/A <author>

5484N/A <contrib>A monkey with a typewriter</contrib>

6784N/A <firstname>Zbigniew</firstname>

5484N/A <surname>Jędrzejewski-Szmek</surname>

5484N/A <email>zbyszek@in.waw.pl</email>

5484N/A </author>

5484N/A </authorgroup>

6784N/A </refentryinfo>

5484N/A

5484N/A <refmeta>

5484N/A <refentrytitle>sd_bus_open_user</refentrytitle>

5484N/A <manvolnum>3</manvolnum>

5484N/A </refmeta>

5484N/A

5484N/A <refnamediv>

5484N/A <refname>sd_bus_open_user</refname>

5484N/A <refname>sd_bus_open_system</refname>

5484N/A <refname>sd_bus_open_system_remote</refname>

5484N/A <refname>sd_bus_open_system_container</refname>

5484N/A

5484N/A <refname>sd_bus_default_user</refname>

5484N/A <refname>sd_bus_default_system</refname>

5484N/A

5484N/A <refpurpose>Open a connection to the system or user bus</refpurpose>

5484N/A </refnamediv>

5484N/A

5484N/A <refsynopsisdiv>

5484N/A <funcsynopsis>

5484N/A <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

5484N/A

5484N/A <funcprototype>

5484N/A <funcdef>int <function>sd_bus_open_user</function></funcdef>

5484N/A <paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_open_system</function></funcdef>

<paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_open_system_remote</function></funcdef>

<paramdef>const char *<parameter>host</parameter></paramdef>

<paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_open_system_container</function></funcdef>

<paramdef>const char *<parameter>machine</parameter></paramdef>

<paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_default_user</function></funcdef>

<paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_bus_default_system</function></funcdef>

<paramdef>sd_bus **<parameter>bus</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_bus_open_user()</function> creates a new bus

object and opens a connection to the user bus.

<function>sd_bus_open_system()</function> does the same, but

connects to the system bus.</para>

<para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment

variable is set

(cf. <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),

it will be used as the address of the user bus. This variable can

contain multiple addresses separated by <literal>;</literal>. If

this variable is not set, a suitable default for the default user

D-Bus instance will be used.</para>

<para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment

variable is set, it will be used as the address of the system

bus. This variable uses the same syntax as

<varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is

not set, a suitable default for the default system D-Bus instance

will be used.</para>

<para><function>sd_bus_open_system_remote()</function> connects to

the system bus on the specified <parameter>host</parameter> using

SSH. <parameter>host</parameter> consists of an optional user name

followed by the <literal>@</literal> symbol, and the hostname.

</para>

<para><function>sd_bus_open_system_remote()</function> connects to

the system bus in the specified <parameter>machine</parameter>,

where <parameter>machine</parameter> is the name of a container.

See

<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

for more information about "machines".</para>

<para><function>sd_bus_default_user()</function> returns a bus

object connected to the user bus. Each thread has its own object, but it

may be passed around. It is created on the first invocation of

<function>sd_bus_default_user()</function>, and subsequent

invocations returns a reference to the same object.</para>

<para><function>sd_bus_default_system()</function> is similar to

<function>sd_bus_default_user()</function>, but connects to the

system bus.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On success, these calls return 0 or a positive

integer. On failure, these calls return a negative

errno-style error code.</para>

</refsect1>

<refsect1>

<title>Reference ownership</title>

<para>Functions <function>sd_bus_open_user()</function>,

<function>sd_bus_open_system()</function>,

<function>sd_bus_open_system_remote()</function>, and

<function>sd_bus_open_system_machine()</function> return a new

object and the caller owns the sole reference. When not needed

anymore, this reference should be destroyed with

<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.

</para>

<para>The functions <function>sd_bus_default_user()</function> and

<function>sd_bus_default_system()</function> do not create a new

reference.</para>

</refsect1>

<refsect1>

<title>Errors</title>

<para>Returned errors may indicate the following problems:</para>

<variablelist>

<varlistentry>

<term><varname>-EINVAL</varname></term>

<listitem><para>Specified parameter is invalid

(<constant>NULL</constant> in case of output

parameters).</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>-ENOMEM</varname></term>

<listitem><para>Memory allocation failed.</para></listitem>

</varlistentry>

<para>In addition, any further connection-related errors may be

by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

</variablelist>

</refsect1>

<refsect1>

<title>Notes</title>

<para><function>sd_bus_open_user()</function> and other functions

described here are available as a shared library, which can be

compiled and linked to with the

<constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

file.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>