From e6ce785d611702532ae71547e78fbb49eff3aded Mon Sep 17 00:00:00 2001
From: igo95862 <igo95862@yandex.ru>
Date: Tue, 17 Nov 2020 12:47:28 +0300
Subject: [PATCH] man: Add a paragraph to sd_bus_call explaning callback
 message lifetime

---
 man/sd_bus_call.xml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml
index fa0089bd22..1f7dfc2e82 100644
--- a/man/sd_bus_call.xml
+++ b/man/sd_bus_call.xml
@@ -89,6 +89,12 @@
     input parameter; it can be used to propagate errors from the callback handler, it will not receive any
     error that was received as method reply.)</para>
 
+    <para>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should
+    not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
+    <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a
+    new reference.</para>
+
     <para>If <parameter>usec</parameter> is zero, the default D-Bus method call timeout is used. See
     <citerefentry><refentrytitle>sd_bus_get_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     </para>