Merge pull request #15153 from keszybz/man-bus-address

Add two man pages for sd-bus

man/rules/meson.build

@@ -139,7 +139,7 @@ manpages = [
  ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
  ['sd_bus_call', '3', ['sd_bus_call_async'], ''],
  ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''],
- ['sd_bus_close', '3', ['sd_bus_flush'], ''],
+ ['sd_bus_close', '3', ['sd_bus_default_flush_close', 'sd_bus_flush'], ''],
  ['sd_bus_creds_get_pid',
   '3',
   ['sd_bus_creds_get_audit_login_uid',
@@ -330,12 +330,15 @@ manpages = [
    'sd_bus_release_name_async',
    'sd_bus_request_name_async'],
   ''],
+ ['sd_bus_set_address', '3', ['sd_bus_get_address'], ''],
  ['sd_bus_set_close_on_exit', '3', ['sd_bus_get_close_on_exit'], ''],
  ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''],
  ['sd_bus_set_description',
   '3',
   ['sd_bus_get_allow_interactive_authorization',
    'sd_bus_get_description',
+   'sd_bus_is_anonymous',
+   'sd_bus_is_trusted',
    'sd_bus_set_allow_interactive_authorization',
    'sd_bus_set_anonymous',
    'sd_bus_set_trusted'],
@@ -360,6 +363,7 @@ manpages = [
   ''],
  ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''],
  ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''],
+ ['sd_bus_start', '3', [], ''],
  ['sd_bus_track_add_name',
   '3',
   ['sd_bus_track_add_sender',

man/sd-bus.xml

@@ -54,6 +54,7 @@
 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_get_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_n_queued_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
@@ -86,6 +87,7 @@
 <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
@@ -96,6 +98,7 @@
 <citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 </literallayout>

man/sd_bus_close.xml

@@ -19,6 +19,7 @@
   <refnamediv>
     <refname>sd_bus_close</refname>
     <refname>sd_bus_flush</refname>
+    <refname>sd_bus_default_flush_close</refname>
 
     <refpurpose>Close and flush a bus connection</refpurpose>
   </refnamediv>
@@ -36,6 +37,11 @@
         <funcdef>int <function>sd_bus_flush</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_bus_default_flush_close</function></funcdef>
+        <paramdef>void</paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -59,6 +65,15 @@
     bus object so that it may be freed. Since these three operations are frequently done together a helper call
     <citerefentry><refentrytitle>sd_bus_flush_close_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> is
     provided that combines them into one.</para>
+
+    <para><function>sd_bus_default_flush_close()</function> is similar to
+    <function>sd_bus_flush_close_unref</function>, but does not take a bus pointer argument and instead
+    iterates over any of the "default" busses opened by
+    <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    and similar calls. <function>sd_bus_default_flush_close()</function> is particularly useful to clean up
+    any busses opened using those calls before the program exits.</para>
   </refsect1>
 
   <refsect1>

man/sd_bus_default.xml

@@ -186,14 +186,14 @@
     <para>Note that entering a container is a privileged operation, and will likely only
     work for the root user on the remote machine.</para>
 
-    <para><function>sd_bus_open_system_machine()</function> connects
+    <para><function>sd_bus_open_system_machine()</function> connects to the system bus in the specified
-    to the system bus in the specified <parameter>machine</parameter>,
+    <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local
-    where <parameter>machine</parameter> is the name of a local
+    container. See
-    container.  See
+    <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    for a description of the address syntax, and
-    for more information about the "machine" concept. Note that
+    <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more
-    connections into local containers are only available to privileged
+    information about the "machine" concept. Note that connections into local containers are only available
-    processes at this time.</para>
+    to privileged processes at this time.</para>
 
     <para>These calls allocate a bus connection object and initiate
     the connection to a well-known bus of some form. An alternative to
@@ -297,7 +297,7 @@
         </varlistentry>
       </variablelist>
 
-      <para>In addition, any further connection-related errors may be by returned. See
+      <para>In addition, other connection-related errors may be returned. See
       <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
     </refsect2>
   </refsect1>
@@ -313,6 +313,7 @@
       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <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><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>

man/sd_bus_new.xml

@@ -87,14 +87,12 @@
     or a related call, and then start the connection with
     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 
-    <para>In most cases, it is a better idea to invoke
+    <para>In most cases, it is better to use
     <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
     <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    or related calls instead of the more low-level
+    or related calls instead of the more low-level <function>sd_bus_new()</function> and
-    <function>sd_bus_new()</function> and
+    <function>sd_bus_start()</function>. The higher-level functions not only allocate a bus object but also
-    <function>sd_bus_start()</function>. The higher-level calls not
+    start the connection to a well-known bus in a single function call.</para>
-    only allocate a bus object but also start the connection to a
-    well-known bus in a single function invocation.</para>
 
     <para><function>sd_bus_ref()</function> increases the reference
     counter of <parameter>bus</parameter> by one.</para>

man/sd_bus_set_address.xml

@@ -0,0 +1,176 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_set_address"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_set_address</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_set_address</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_set_address</refname>
+    <refname>sd_bus_get_address</refname>
+
+    <refpurpose>Set or query the address of the bus connection</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_set_address</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>const char* <parameter>address</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_get_address</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>const char** <parameter>address</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_set_address()</function> configures a list of addresses of bus brokers to try to
+    connect to from a subsequent
+    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
+    The argument is a <literal>;</literal>-separated list of addresses to try. Each item must be one of the
+    following:
+    </para>
+
+    <itemizedlist>
+      <listitem>
+        <para>A unix socket address specified as
+        <literal>unix:guid=<replaceable>guid</replaceable>,path=<replaceable>path</replaceable></literal> or
+        <literal>unix:guid=<replaceable>guid</replaceable>,abstract=<replaceable>path</replaceable></literal>.
+        Exactly one of the <varname>path=</varname> and <varname>abstract=</varname> keys must be present,
+        while <varname>guid=</varname> is optional.</para>
+      </listitem>
+
+      <listitem>
+        <para>A TCP socket address specified as
+        <literal>tcp:[guid=<replaceable>guid</replaceable>,][host=<replaceable>host</replaceable>][,port=<replaceable>port</replaceable>][,family=<replaceable>family</replaceable>]</literal>.
+        One or both of the <varname>host=</varname> and <varname>port=</varname> keys must be present, while
+        the rest is optional. <replaceable>family</replaceable> may be either <option>ipv4</option> or
+        <option>ipv6</option>.</para>
+      </listitem>
+      
+      <listitem>
+        <para>An executable to spawn specified as
+        <literal>unixexec:guid=<replaceable>guid</replaceable>,path=<replaceable>path</replaceable>,argv1=<replaceable>argument</replaceable>,argv2=<replaceable>argument</replaceable>,...</literal>.
+        The <varname>path=</varname> key must be present, while <varname>guid=</varname> is optional.</para>
+      </listitem>
+      
+      <listitem>
+        <para>A machine (container) to connect to specified as
+        <literal>x-machine-unix:guid=<replaceable>guid</replaceable>,machine=<replaceable>machine</replaceable>,pid=<replaceable>pid</replaceable></literal>.
+        Exactly one of the <varname>machine=</varname> and <varname>pid=</varname> keys must be present,
+        while <varname>guid=</varname> is optional. <parameter>machine</parameter> is the name of a local
+        container. See
+        <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        more information about the "machine" concept. <literal>machine=.host</literal> may be used to specify
+        the host machine. A connection to the standard system bus socket inside of the specified machine will
+        be created.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>In all cases, parameter <parameter>guid</parameter> is an identifier of the remote peer, in the
+    syntax accepted by
+    <citerefentry><refentrytitle>sd_id128_from_string</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    If specified, the identifier returned by the peer after the connection is established will be checked and
+    the connection will be rejected in case of a mismatch.</para>
+
+    <para>Note that the addresses passed to <function>sd_bus_set_address()</function> may not be verified
+    immediately. If they are invalid, an error may be returned e.g. from a subsequent call to
+    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_get_address()</function> returns any previously set addresses. In addition to
+    being explicitly set by <function>sd_bus_set_address()</function>, the address will also be set
+    automatically by
+    <citerefentry><refentrytitle>sd_bus_open</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
+    similar calls, based on environment variables or built-in defaults.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these functions return a non-negative integer. On failure, they return a negative
+    errno-style error code.</para>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>The input parameters <parameter>bus</parameter> or <parameter>address</parameter> are <constant>NULL</constant>.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>The bus object <parameter>bus</parameter> could not be resolved.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
+
+          <listitem><para>The input parameter <parameter>bus</parameter> is in a wrong state
+          (<function>sd_bus_set_address()</function> may only be called once on a newly-created bus object).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The bus object <parameter>bus</parameter> was created in a different
+          process.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENODATA</constant></term>
+
+          <listitem><para>The bus object <parameter>bus</parameter> has no address configured.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>

man/sd_bus_set_description.xml

@@ -19,7 +19,9 @@
     <refname>sd_bus_set_description</refname>
     <refname>sd_bus_get_description</refname>
     <refname>sd_bus_set_anonymous</refname>
+    <refname>sd_bus_is_anonymous</refname>
     <refname>sd_bus_set_trusted</refname>
+    <refname>sd_bus_is_trusted</refname>
     <refname>sd_bus_set_allow_interactive_authorization</refname>
     <refname>sd_bus_get_allow_interactive_authorization</refname>
 
@@ -48,12 +50,22 @@
         <paramdef>int <parameter>b</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_is_anonymous</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_set_trusted</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
         <paramdef>int <parameter>b</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>int <function>sd_bus_is_trusted</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -75,7 +87,7 @@
     and freed when the bus object is deallocated. The
     <parameter>description</parameter> argument may be <constant>NULL</constant>, in
     which case the description is unset. This function must be called before the bus
-    has been started.</para>
+    is started.</para>
 
     <para><function>sd_bus_get_description()</function> returns a description string
     in <parameter>description</parameter>. This string may have been previously set
@@ -87,14 +99,20 @@
 
     <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous
     authentication", i.e. lack of authentication, of the bus peer. This function must
-    be called before the bus has been started. See the <ulink
+    be called before the bus is started. See the <ulink
     url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">Authentication
     Mechanisms</ulink> section of the D-Bus specification for details.</para>
 
+    <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows anonymous
+    authentication (in the sense described in previous paragraph).</para>
+
     <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
     <parameter>bus</parameter> object. If true, all connections on the bus are
-    trusted and access to all privileged and unprivileged methods is granted.  This
+    trusted and access to all privileged and unprivileged methods is granted. This
-    function must be called before the bus has been started.</para>
+    function must be called before the bus is started.</para>
+
+    <para><function>sd_bus_is_trusted()</function> returns true if the bus connection is trusted (in the
+    sense described in previous paragraph).</para>
 
     <para><function>sd_bus_set_allow_interactive_authorization()</function>
     enables or disables interactive authorization for method calls. If true,

man/sd_bus_start.xml

@@ -0,0 +1,124 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_start"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_start</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_start</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_start</refname>
+
+    <refpurpose>Initiate a bus connection to the D-bus broker daemon
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_start</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_start()</function> connects an existing bus connection object to the D-Bus
+    broker daemon, usually
+    <citerefentry project='die-net'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    or
+    <citerefentry project='mankier'><refentrytitle>dbus-broker</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    The mechanism to use for the connection must be configured before the call to
+    <function>sd_bus_start()</function>, using one of
+    <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or
+    <citerefentry><refentrytitle>sd_bus_set_exec</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    <function>sd_bus_start()</function> will open the connection socket or spawn the executable as
+    needed, and asynchronously start a <function>org.freedesktop.DBus.Hello()</function> call. The
+    answer to the Hello call will be processed later from
+    <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
+    opening of the connection or queuing of the asynchronous call fail, the connection will be closed with
+    <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>In most cases, it is better to use
+    <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    or related calls instead of the more low-level <function>sd_bus_new()</function> and
+    <function>sd_bus_start()</function>. The higher-level functions not only allocate a bus object but also
+    start the connection to a well-known bus in a single function call.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, this function returns a non-negative integer. On failure, it returns a negative
+    errno-style error code.</para>
+
+    <refsect2 id='errors'>
+      <title>Errors</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>The input parameter <parameter>bus</parameter> is <constant>NULL</constant>.
+          </para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>Bus object <parameter>bus</parameter> could not be resolved.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
+
+          <listitem><para>The input parameter <parameter>bus</parameter> is in a wrong state
+          (<function>sd_bus_start()</function> may only be called once on a newly-created bus object).</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The bus object <parameter>bus</parameter> was created in a different
+          process.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>In addition, other connection-related errors may be returned. See
+      <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>

src/libsystemd/sd-bus/sd-bus.c

@@ -980,9 +980,8 @@ static int parse_container_unix_address(sd_bus *b, const char **p, char **guid)
                         return -EINVAL;
 
                 free_and_replace(b->machine, machine);
-        } else {
+        } else
                 b->machine = mfree(b->machine);
-        }
 
         if (pid) {
                 r = parse_pid(pid, &b->nspid);
@@ -1271,10 +1270,7 @@ int bus_set_address_system(sd_bus *b) {
         assert(b);
 
         e = secure_getenv("DBUS_SYSTEM_BUS_ADDRESS");
-        if (e)
+        return sd_bus_set_address(b, e ?: DEFAULT_SYSTEM_BUS_ADDRESS);
-                return sd_bus_set_address(b, e);
-
-        return sd_bus_set_address(b, DEFAULT_SYSTEM_BUS_ADDRESS);
 }
 
 _public_ int sd_bus_open_system_with_description(sd_bus **ret, const char *description) {
@@ -1319,29 +1315,30 @@ _public_ int sd_bus_open_system(sd_bus **ret) {
 }
 
 int bus_set_address_user(sd_bus *b) {
-        const char *e;
+        const char *a;
-        _cleanup_free_ char *ee = NULL, *s = NULL;
+        _cleanup_free_ char *_a = NULL;
 
         assert(b);
 
-        e = secure_getenv("DBUS_SESSION_BUS_ADDRESS");
+        a = secure_getenv("DBUS_SESSION_BUS_ADDRESS");
-        if (e)
+        if (!a) {
-                return sd_bus_set_address(b, e);
+                const char *e;
+                _cleanup_free_ char *ee = NULL;
 
-        e = secure_getenv("XDG_RUNTIME_DIR");
+                e = secure_getenv("XDG_RUNTIME_DIR");
-        if (!e)
+                if (!e)
-                return -ENOENT;
+                        return -ENOENT;
 
-        ee = bus_address_escape(e);
+                ee = bus_address_escape(e);
-        if (!ee)
+                if (!ee)
-                return -ENOMEM;
+                        return -ENOMEM;
 
-        if (asprintf(&s, DEFAULT_USER_BUS_ADDRESS_FMT, ee) < 0)
+                if (asprintf(&_a, DEFAULT_USER_BUS_ADDRESS_FMT, ee) < 0)
-                return -ENOMEM;
+                        return -ENOMEM;
+                a = _a;
+        }
 
-        b->address = TAKE_PTR(s);
+        return sd_bus_set_address(b, a);
-
-        return 0;
 }
 
 _public_ int sd_bus_open_user_with_description(sd_bus **ret, const char *description) {

src/shared/bus-util.c

@@ -115,36 +115,16 @@ int bus_event_loop_with_idle(
                         return r;
 
                 if (r == 0 && !exiting && idle) {
+                        /* Inform the service manager that we are going down, so that it will queue all
+                         * further start requests, instead of assuming we are already running. */
+                        sd_notify(false, "STOPPING=1");
 
-                        r = sd_bus_try_close(bus);
+                        r = bus_async_unregister_and_exit(e, bus, name);
-                        if (r == -EBUSY)
-                                continue;
-
-                        /* Fallback for dbus1 connections: we
-                         * unregister the name and wait for the
-                         * response to come through for it */
-                        if (r == -EOPNOTSUPP) {
-
-                                /* Inform the service manager that we
-                                 * are going down, so that it will
-                                 * queue all further start requests,
-                                 * instead of assuming we are already
-                                 * running. */
-                                sd_notify(false, "STOPPING=1");
-
-                                r = bus_async_unregister_and_exit(e, bus, name);
-                                if (r < 0)
-                                        return r;
-
-                                exiting = true;
-                                continue;
-                        }
-
                         if (r < 0)
                                 return r;
 
-                        sd_event_exit(e, 0);
+                        exiting = true;
-                        break;
+                        continue;
                 }
         }
 

src/systemd/sd-bus.h

@@ -177,7 +177,7 @@ int sd_bus_get_sender(sd_bus *bus, const char **ret);
 
 int sd_bus_start(sd_bus *bus);
 
-int sd_bus_try_close(sd_bus *bus);
+int sd_bus_try_close(sd_bus *bus) _sd_deprecated_; /* deprecated */
 void sd_bus_close(sd_bus *bus);
 
 sd_bus *sd_bus_ref(sd_bus *bus);

tools/meson-check-api-docs.sh

@@ -6,7 +6,7 @@ sd_total=0
 udev_good=0
 udev_total=0
 
-for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | sort -u` ; do
+for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | grep -wv sd_bus_try_close | sort -u` ; do
     if test -f ${MESON_BUILD_ROOT}/man/$symbol.3 ; then
         echo "✓ Symbol $symbol() is documented."
         good=1