Prep v239: Add missing updates that evaded migration.

[elogind.git] / man / sd_bus_default.xml

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 2605edf4fc3b1f8535fd22a00d50a9a1c7496062..548e053b89f3ba490fec60dc37337bc6334c48b5 100644 (file)
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -4,26 +4,13 @@
 
 <!--
   SPDX-License-Identifier: LGPL-2.1+
-
-  This file is part of systemd.
-
-  Copyright 2014 Zbigniew Jędrzejewski-Szmek
 -->
 
-<refentry id="sd_bus_default">
+<refentry id="sd_bus_default" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_default</title>
     <productname>systemd</productname>
-
-    <authorgroup>
-      <author>
-        <contrib>A monkey with a typewriter</contrib>
-        <firstname>Zbigniew</firstname>
-        <surname>Jędrzejewski-Szmek</surname>
-        <email>zbyszek@in.waw.pl</email>
-      </author>
-    </authorgroup>
   </refentryinfo>
 
   <refmeta>
@@ -206,21 +193,26 @@
     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     to drop the reference.</para>
 
-    <para>Queued but unwritten/unread messages also keep a reference
-    to their bus connection object. For this reason, even if an
-    application dropped all references to a bus connection, it might
-    not get destroyed right away. Until all incoming queued
-    messages are read, and until all outgoing unwritten messages are
-    written, the bus object will stay
-    alive. <function>sd_bus_flush()</function> may be used to write
-    all outgoing queued messages so they drop their references. To
-    flush the unread incoming messages, use
-    <function>sd_bus_close()</function>, which will also close the bus
-    connection. When using the default bus logic, it is a good idea to
-    first invoke <function>sd_bus_flush()</function> followed by
-    <function>sd_bus_close()</function> when a thread or process
-    terminates, and thus its bus connection object should be
-    freed.</para>
+    <para>Queued but unwritten/unread messages keep a reference to their bus connection object. For this reason, even
+    if an application dropped all references to a bus connection, it might not get destroyed right away. Until all
+    incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay
+    alive. <function>sd_bus_flush()</function> may be used to write all outgoing queued messages so they drop their
+    references. To flush the unread incoming messages, use <function>sd_bus_close()</function>, which will also close
+    the bus connection. When using the default bus logic, it is a good idea to first invoke
+    <function>sd_bus_flush()</function> followed by <function>sd_bus_close()</function> when a thread or process
+    terminates, and thus its bus connection object should be freed.</para>
+
+    <para>Normally, slot objects (as created by
+    <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar
+    calls) keep a reference to their bus connection object, too. Thus, as long as a bus slot object remains referenced
+    its bus object will remain allocated too. Optionally, bus slot objects may be placed in "floating" mode. When in
+    floating mode the life cycle of the bus slot object is bound to the bus object, i.e. when the bus object is freed
+    the bus slot object is automatically unreferenced too. The floating state of a slot object may be controlled
+    explicitly with
+    <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    though usually floating bus slot objects are created by passing <constant>NULL</constant> as the
+    <parameter>slot</parameter> parameter of <function>sd_bus_add_match()</function> and related calls, thus indicating
+    that the caller is not directly interested in referencing and managing the bus slot object.</para>
 
     <para>The life cycle of the default bus connection should be the
     responsibility of the code that creates/owns the thread the
@@ -276,16 +268,7 @@
     by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_open_user()</function> and the other
-    functions described here are available as a shared library, which
-    can be compiled and linked to with the
-    <constant>libelogind</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
-  </refsect1>
+  <xi:include href="libelogind-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>