sd_bus_open_user

systemd
A monkey with a typewriter Zbigniew Jędrzejewski-Szmek zbyszek@in.waw.pl
sd_bus_open_user 3
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

    #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