From db03761e16f945fdc639f88a0c316eeda665980b Mon Sep 17 00:00:00 2001
From: Umut Tezduyar Lindskog <umuttl@axis.com>
Date: Fri, 10 Jul 2015 14:31:53 +0200
Subject: [PATCH] man: sd_unref does not necessarily free the bus

Document that sd_unref() does not necessarily free the bus,
even if no part of the program explicitly refs it, due to
the queued messages.
---
 man/sd_bus_default.xml |  6 ++++++
 man/sd_bus_new.xml     | 16 +++++++---------
 2 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index 95b347bdfd..782dfb5706 100644
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -219,6 +219,12 @@
     one. Use
     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     to drop the reference.</para>
+
+    <para>Queued messages also keep a reference to the bus. For this reason, just
+    because no application is having a reference to the bus does not mean that
+    the bus object will be destroyed. Until all the messages are sent, the bus object
+    will stay alive. <function>sd_bus_flush</function> can be used to send all the
+    queued messages so they drop their references.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml
index 44744a0029..aff2ed2e83 100644
--- a/man/sd_bus_new.xml
+++ b/man/sd_bus_new.xml
@@ -77,8 +77,8 @@
     <para><function>sd_bus_new()</function> creates a new bus
     object. This object is reference-counted, and will be destroyed
     when all references are gone. Initially, the caller of this
-    function owns the sole reference. The bus object will not be
-    connected to any bus initially. To connect it to a bus, make sure
+    function owns the sole reference and the bus object will not be
+    connected to any bus. To connect it to a bus, make sure
     to set an address with
     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     or a related call, and then start the connection with
@@ -94,15 +94,13 @@
     well-known bus in a single function invocation.</para>
 
     <para><function>sd_bus_ref()</function> creates a new reference to
-    <parameter>bus</parameter>. This bus object will not be destroyed
-    until <function>sd_bus_unref()</function> has been called as many
-    times plus once more. Once the reference count has dropped to
-    zero, <parameter>bus</parameter> cannot be used anymore, so
-    further calls to <function>sd_bus_ref()</function> or
-    <function>sd_bus_unref()</function> are illegal.</para>
+    <parameter>bus</parameter>.</para>
 
     <para><function>sd_bus_unref()</function> destroys a reference to
-    <parameter>bus</parameter>.</para>
+    <parameter>bus</parameter>. Once the reference count has dropped
+    to zero, <parameter>bus</parameter> cannot be used anymore, so
+    further calls to <function>sd_bus_ref()</function> or
+    <function>sd_bus_unref()</function> are illegal.</para>
   </refsect1>
 
   <refsect1>