sd_bus_open_user.xml revision cd6d5e1c7631d6e74cb04be279dee22e423e08b8
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangThis file is part of systemd.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangCopyright 2014 Zbigniew Jędrzejewski-Szmek
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yangsystemd is free software; you can redistribute it and/or modify it
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yangunder the terms of the GNU Lesser General Public License as published by
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yangthe Free Software Foundation; either version 2.1 of the License, or
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang(at your option) any later version.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yangsystemd is distributed in the hope that it will be useful, but
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangWITHOUT ANY WARRANTY; without even the implied warranty of
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangLesser General Public License for more details.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan YangYou should have received a copy of the GNU Lesser General Public License
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yangalong with systemd; If not, see <http://www.gnu.org/licenses/>.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <refentryinfo>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <authorgroup>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </authorgroup>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </refentryinfo>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <refnamediv>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <refpurpose>Open a connection to the system or user bus</refpurpose>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </refnamediv>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <refsynopsisdiv>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcsynopsis>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_open_user</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_open_system</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>const char *<parameter>host</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_open_system_container</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>const char *<parameter>machine</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_default_user</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <funcdef>int <function>sd_bus_default_system</function></funcdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcprototype>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </funcsynopsis>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </refsynopsisdiv>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_open_user()</function> creates a new bus
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang object and opens a connection to the the user bus.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_open_system()</function> does the same, but
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang connects to the system bus.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>If <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang variable is set
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang (c.f. <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang it will be used as the address of the user bus. This variable can
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang contain multiple addresses separated by <literal>;</literal>. If
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang this variable is not set, a suitable default for the default user
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang D-Bus instance will be used.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>If <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang variable is set, it will be used as the address of the system
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang bus. This variable uses the same syntax as
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang not set, a suitable default for the default system D-Bus instance
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang will be used.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_open_system_remote()</function> connects to
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang the system bus on the specified <parameter>host</parameter> using
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang SSH. <parameter>host</parameter> consists of an optional user name
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang followed by the <literal>@</literal> symbol, and the hostname.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_open_system_remote()</function> connects to
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang the system bus in the specified <parameter>machine</parameter>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang where <parameter>machine</parameter> is the name of a container.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang for more information about "machines".</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_default_user()</function> returns a bus
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang object connected to the user bus. This bus object is shared
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang per-thread. It is created on the first invocation of
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_default_user()</function>, and subsequent
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang invocations returns a reference to the same object.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_default_system()</function> is similar to
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_default_user()</function>, but connects to the
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang system bus.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>On success, these calls return 0 or a positive
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang integer. On failure, these calls return a negative
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang errno-style error code.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>Functions <function>sd_bus_open_user()</function>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_open_system_remote()</function>, and
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_open_system_machine()</function> return a new
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang object and the caller owns the sole reference. When not needed
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang anymore, this reference should be destroyed with
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>Functions <function>sd_bus_default_user()</function> and
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <function>sd_bus_default_system()</function> do not create a new
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang reference.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>Returned errors may indicate the following problems:</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <variablelist>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <varlistentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </varlistentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <varlistentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <listitem><para>Memory allocation failed.</para></listitem>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </varlistentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para>In addition, any further connection-related errors may be
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang </variablelist>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <para><function>sd_bus_open_user()</function> and other functions
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang described here are available as a shared library, which can be
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang compiled and linked to with the
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang file.</para>
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
e0c7a4e07df8906dc513b73dd20bc7ccddcce950Boyuan Yang <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>