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 fa0089bd22196919351e43462af26e0e6b2b7ced..1f7dfc2e827828a3b58d0888a7c29346bce0a960 100644 (file)
--- 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>