SD_BUS_OPEN_USER(3)

NAME
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

SYNOPSIS

#include <systemd/sd-bus.h>

int sd_bus_open_user(sd_bus **bus);

int sd_bus_open_system(sd_bus **bus);

int sd_bus_open_system_remote(const char *host, sd_bus **bus);

int sd_bus_open_system_container(const char *machine, sd_bus **bus);

int sd_bus_default_user(sd_bus **bus);

int sd_bus_default_system(sd_bus **bus);

DESCRIPTION

sd_bus_open_user() creates a new bus object and opens a connection to the user bus. sd_bus_open_system() does the same, but connects to the system bus.

If the $DBUS_SESSION_BUS_ADDRESS environment variable is set (cf. environ(7)), it will be used as the address of the user bus. This variable can contain multiple addresses separated by ";". If this variable is not set, a suitable default for the default user D-Bus instance will be used.

If the $DBUS_SYSTEM_BUS_ADDRESS environment variable is set, it will be used as the address of the system bus. This variable uses the same syntax as $DBUS_SESSION_BUS_ADDRESS/. If this variable is not set, a suitable default for the default system D-Bus instance will be used.

sd_bus_open_system_remote() connects to the system bus on the specified host using SSH. host consists of an optional user name followed by the "@" symbol, and the hostname.

sd_bus_open_system_remote() connects to the system bus in the specified machine, where machine is the name of a container. See machinectl(1) for more information about "machines".

sd_bus_default_user() 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 sd_bus_default_user(), and subsequent invocations returns a reference to the same object.

sd_bus_default_system() is similar to sd_bus_default_user(), but connects to the system bus.

RETURN VALUE

On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code.

REFERENCE OWNERSHIP

Functions sd_bus_open_user(), sd_bus_open_system(), sd_bus_open_system_remote(), and sd_bus_open_system_machine() return a new object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed with sd_bus_unref(3).

The functions sd_bus_default_user() and sd_bus_default_system() do not create a new reference.

ERRORS

Returned errors may indicate the following problems:

-EINVAL
    Specified parameter is invalid (NULL in case of output parameters).

-ENOMEM
    Memory allocation failed.

In addition, any further connection-related errors may be by returned. See sd_bus_send(3).

NOTES

sd_bus_open_user() and other functions described here are available as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.

SEE ALSO

systemd(1), sd-bus(3), sd_bus_new(3), sd_bus_ref(3), sd_bus_unref(3), ssh(1), systemd-machined.service(8), machinectl(1)