From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 23 Sep 2020 08:09:53 +0000 (+0200)
Subject: man: mention that sd_bus_send() buffers locally, and sd_bus_process() is needed to... 
X-Git-Tag: v247-rc1~142
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=533ee38b56e881a49481bdc095793c294acce121;p=thirdparty%2Fsystemd.git

man: mention that sd_bus_send() buffers locally, and sd_bus_process() is needed to flush it out

Prompted-by: #17128
---

diff --git a/man/sd_bus_send.xml b/man/sd_bus_send.xml
index 2cdf436db2b..233dd7c4fa6 100644
--- a/man/sd_bus_send.xml
+++ b/man/sd_bus_send.xml
@@ -68,6 +68,14 @@
     single receiver). It's behavior is similar to calling
     <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     followed by calling <function>sd_bus_send()</function>.</para>
+
+    <para><function>sd_bus_send()</function>/<function>sd_bus_send_to()</function> will write the message
+    directly to the underlying transport (e.g. kernel socket buffer) if possible. If the connection is not
+    set up fully yet the message is queued locally. If the transport buffers are congested any unwritten
+    message data is queued locally, too. If the connection has been closed or is currently being closed the
+    call fails.
+    <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> should
+    be invoked to write out any queued message data to the transport.</para>
   </refsect1>
 
   <refsect1>
@@ -142,7 +150,8 @@
       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>