'\" t
.TH "SD_BUS_OPEN_USER" "3" "" "systemd 219" "sd_bus_open_user"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.HP \w'int\ sd_bus_open_user('u
.BI "int sd_bus_open_user(sd_bus\ **" "bus" ");"
.HP \w'int\ sd_bus_open_system('u
.BI "int sd_bus_open_system(sd_bus\ **" "bus" ");"
.HP \w'int\ sd_bus_open_system_remote('u
.BI "int sd_bus_open_system_remote(const\ char\ *" "host" ", sd_bus\ **" "bus" ");"
.HP \w'int\ sd_bus_open_system_container('u
.BI "int sd_bus_open_system_container(const\ char\ *" "machine" ", sd_bus\ **" "bus" ");"
.HP \w'int\ sd_bus_default_user('u
.BI "int sd_bus_default_user(sd_bus\ **" "bus" ");"
.HP \w'int\ sd_bus_default_system('u
.BI "int sd_bus_default_system(sd_bus\ **" "bus" ");"
.SH "DESCRIPTION"
.PP
\fBsd_bus_open_user()\fR
creates a new bus object and opens a connection to the user bus\&.
\fBsd_bus_open_system()\fR
does the same, but connects to the system bus\&.
.PP
If the
\fI$DBUS_SESSION_BUS_ADDRESS\fR
environment variable is set (cf\&.
\fBenviron\fR(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\&.
.PP
If the
\fI$DBUS_SYSTEM_BUS_ADDRESS\fR
environment variable is set, it will be used as the address of the system bus\&. This variable uses the same syntax as
\fI$DBUS_SESSION_BUS_ADDRESS\fR/\&. If this variable is not set, a suitable default for the default system D\-Bus instance will be used\&.
.PP
\fBsd_bus_open_system_remote()\fR
connects to the system bus on the specified
\fIhost\fR
using SSH\&.
\fIhost\fR
consists of an optional user name followed by the
"@"
symbol, and the hostname\&.
.PP
\fBsd_bus_open_system_container()\fR
connects to the system bus in the specified
\fImachine\fR, where
\fImachine\fR
is the name of a container\&. See
\fBmachinectl\fR(1)
for more information about "machines"\&.
.PP
\fBsd_bus_default_user()\fR
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
\fBsd_bus_default_user()\fR, and subsequent invocations returns a reference to the same object\&.
.PP
\fBsd_bus_default_system()\fR
is similar to
\fBsd_bus_default_user()\fR, but connects to the system bus\&.
.SH "RETURN VALUE"
.PP
On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
.SH "REFERENCE OWNERSHIP"
.PP
Functions
\fBsd_bus_open_user()\fR,
\fBsd_bus_open_system()\fR,
\fBsd_bus_open_system_remote()\fR, and
\fBsd_bus_open_system_machine()\fR
return a new object and the caller owns the sole reference\&. When not needed anymore, this reference should be destroyed with
\fBsd_bus_unref\fR(3)\&.
.PP
The functions
\fBsd_bus_default_user()\fR
and
\fBsd_bus_default_system()\fR
do not create a new reference\&.
.SH "ERRORS"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
Specified parameter is invalid (\fBNULL\fR
in case of output parameters)\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.PP
In addition, any further connection\-related errors may be by returned\&. See
\fBsd_bus_send\fR(3)\&.
.SH "NOTES"
.PP
\fBsd_bus_open_user()\fR
and other functions described here are available as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-bus\fR(3),
\fBsd_bus_new\fR(3),
\fBsd_bus_ref\fR(3),
\fBsd_bus_unref\fR(3),
\fBssh\fR(1),
\fBsystemd-machined.service\fR(8),
\fBmachinectl\fR(1)