man: Add a paragraph to sd_bus_call explaning callback message lifetime

1 files changed, 6 insertions, 0 deletions

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>