<refname>sd_bus_open_with_description</refname>
<refname>sd_bus_open_user</refname>
<refname>sd_bus_open_user_with_description</refname>
+ <refname>sd_bus_open_user_machine</refname>
<refname>sd_bus_open_system</refname>
<refname>sd_bus_open_system_with_description</refname>
<refname>sd_bus_open_system_remote</refname>
<paramdef>const char *<parameter>description</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_bus_open_user_machine</function></funcdef>
+ <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+ <paramdef>const char *<parameter>machine</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_bus_open_system</function></funcdef>
<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
<title>Description</title>
<para><function>sd_bus_default()</function> acquires a bus
- connection object to the user bus when invoked in user context, or
- to the system bus otherwise. The connection object is associated
- with the calling thread. Each time the function is invoked from
- the same thread, the same object is returned, but its reference
- count is increased by one, as long as at least one reference is
- kept. When the last reference to the connection is dropped (using
- the
+ connection object to the user bus when invoked from within a user
+ slice (any session under <literal>user-*.slice</literal>, e.g.:
+ <literal>user@1000.service</literal>), or to the system bus
+ otherwise. The connection object is associated with the calling
+ thread. Each time the function is invoked from the same thread,
+ the same object is returned, but its reference count is increased
+ by one, as long as at least one reference is kept. When the last
+ reference to the connection is dropped (using the
<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call), the connection is terminated. Note that the connection is
not automatically terminated when the associated thread ends. It
<para><function>sd_bus_open_system_remote()</function> connects to the system bus on
the specified host using
- <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ <citerefentry project='man-pages'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<parameter>host</parameter> consists of an optional user name followed by the
<literal>@</literal> symbol, and the hostname, optionally followed by a
<literal>:</literal> and a port, optionally followed by a
work for the root user on the remote machine.</para>
<para><function>sd_bus_open_system_machine()</function> connects to the system bus in the specified
- <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local
- container. See
+ <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local container,
+ possibly prefixed by a user name and a separating <literal>@</literal>. If the container name is
+ specified as the special string <literal>.host</literal> the connection is made to the local system. This
+ is useful to connect to the local system bus as specific user, e.g. <literal>foobar@.host</literal> to
+ connect to the local system bus as local user <literal>foobar</literal>. If the <literal>@</literal>
+ syntax is used either the left-hand side or the right-hand side may be omitted (but not both) in which
+ case the local user name or <literal>.host</literal> is implied. If the <literal>@</literal> syntax is
+ not used the connection is always made as root user. See
<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for a description of the address syntax, and
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more
information about the "machine" concept. Note that connections into local containers are only available
to privileged processes at this time.</para>
+ <para><function>sd_bus_open_user_machine()</function> is similar to
+ <function>sd_bus_open_system_machine()</function>, but connects to the user bus of the root user, or if
+ the <literal>@</literal> syntax is used, of the specified user.</para>
+
<para>These calls allocate a bus connection object and initiate
the connection to a well-known bus of some form. An alternative to
using these high-level calls is to create an unconnected bus
<title>Reference ownership</title>
<para>The functions <function>sd_bus_open()</function>,
<function>sd_bus_open_user()</function>,
+ <function>sd_bus_open_user_machine()</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
<listitem><para>The requested bus type is not available because of invalid environment (for example
the user session bus is not available because <varname>$XDG_RUNTIME_DIR</varname> is not set).
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v247"/></listitem>
</varlistentry>
<varlistentry>
<citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><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>
projects / thirdparty / systemd.git / blobdiff