From: igo95862 <igo95862@yandex.ru>
Date: Tue, 17 Nov 2020 09:47:28 +0000 (+0300)
Subject: man: Add a paragraph to sd_bus_call explaning callback message lifetime
X-Git-Tag: v247~58
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e6ce785d611702532ae71547e78fbb49eff3aded;p=thirdparty%2Fsystemd.git

man: Add a paragraph to sd_bus_call explaning callback message lifetime
---

diff --git a/man/sd_bus_call.xml b/man/sd_bus_call.xml
index fa0089bd221..1f7dfc2e827 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>