man/sd_bus_send.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_send"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_send</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_send</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_send</refname>
  21     <refname>sd_bus_send_to</refname>
  22     <refname>sd_bus_message_send</refname>
  23
  24     <refpurpose>Queue a D-Bus message for transfer</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <funcsynopsis>
  29       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  30
  31       <funcprototype>
  32         <funcdef>int <function>sd_bus_send</function></funcdef>
  33         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  34         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  35         <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
  36       </funcprototype>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_bus_send_to</function></funcdef>
  40         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  41         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  42         <paramdef>const char *<parameter>destination</parameter></paramdef>
  43         <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int sd_bus_message_send</funcdef>
  48         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  49       </funcprototype>
  50     </funcsynopsis>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para><function>sd_bus_send()</function> queues the bus message object <parameter>m</parameter> for
  57     transfer. If <parameter>bus</parameter> is <constant>NULL</constant>, the bus that
  58     <parameter>m</parameter> is attached to is used. <parameter>bus</parameter> only needs to be set when the
  59     message is sent to a different bus than the one it is attached to, for example when forwarding messages.
  60     If the output parameter <parameter>cookie</parameter> is not <constant>NULL</constant>, it is set to the
  61     message identifier. This value can later be used to match incoming replies to their corresponding
  62     messages. If <parameter>cookie</parameter> is set to <constant>NULL</constant> and the message is not
  63     sealed, <function>sd_bus_send()</function> assumes the message <parameter>m</parameter> does not expect a
  64     reply and adds the necessary headers to indicate this.</para>
  65
  66     <para>Note that in most scenarios, <function>sd_bus_send()</function> should not be called
  67     directly. Instead, use higher level functions such as
  68     <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
  69     <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  70     which call <function>sd_bus_send()</function> internally.</para>
  71
  72     <para><function>sd_bus_send_to()</function> is a shorthand for sending a message to a specific
  73     destination. It's main use case is to simplify sending unicast signal messages (signals that only have a
  74     single receiver). It's behavior is similar to calling
  75     <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  76     followed by calling <function>sd_bus_send()</function>.</para>
  77
  78     <para><function>sd_bus_send()</function>/<function>sd_bus_send_to()</function> will write the message
  79     directly to the underlying transport (e.g. kernel socket buffer) if possible. If the connection is not
  80     set up fully yet the message is queued locally. If the transport buffers are congested any unwritten
  81     message data is queued locally, too. If the connection has been closed or is currently being closed the
  82     call fails.
  83     <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> should
  84     be invoked to write out any queued message data to the transport.</para>
  85
  86     <para><function>sd_bus_message_send()</function> is the same as <function>sd_bus_send()</function> but
  87     without the first and last argument. <function>sd_bus_message_send(m)</function> is equivalent to
  88     <function>sd_bus_send(sd_bus_message_get_bus(m), m, NULL)</function>.</para>
  89   </refsect1>
  90
  91   <refsect1>
  92     <title>Return Value</title>
  93
  94     <para>On success, these functions return a non-negative integer. On failure, they return a negative
  95     errno-style error code.</para>
  96
  97     <refsect2 id='errors'>
  98       <title>Errors</title>
  99
 100       <para>Returned errors may indicate the following problems:</para>
 101
 102       <variablelist>
 103         <varlistentry>
 104           <term><constant>-EINVAL</constant></term>
 105
 106           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
 107           </para>
 108
 109           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 110         </varlistentry>
 111
 112         <varlistentry>
 113           <term><constant>-EOPNOTSUPP</constant></term>
 114
 115           <listitem><para>The bus connection does not support sending file descriptors.
 116           </para>
 117
 118           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 119         </varlistentry>
 120
 121         <varlistentry>
 122           <term><constant>-ECHILD</constant></term>
 123
 124           <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
 125           process after <function>fork()</function>.</para>
 126
 127           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 128         </varlistentry>
 129
 130         <varlistentry>
 131           <term><constant>-ENOBUFS</constant></term>
 132
 133           <listitem><para>The bus connection's write queue is full.</para>
 134
 135           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 136         </varlistentry>
 137
 138         <varlistentry>
 139           <term><constant>-ENOTCONN</constant></term>
 140
 141           <listitem><para>The input parameter <parameter>bus</parameter> is
 142           <constant>NULL</constant> or the bus is not connected.</para>
 143
 144           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 145         </varlistentry>
 146
 147         <varlistentry>
 148           <term><constant>-ECONNRESET</constant></term>
 149
 150           <listitem><para>The bus connection was closed while waiting for the response.
 151           </para>
 152
 153           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157           <term><constant>-ENOMEM</constant></term>
 158
 159           <listitem><para>Memory allocation failed.</para>
 160
 161           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 162         </varlistentry>
 163       </variablelist>
 164     </refsect2>
 165   </refsect1>
 166
 167   <xi:include href="libsystemd-pkgconfig.xml" />
 168
 169   <refsect1>
 170     <title>History</title>
 171     <para><function>sd_bus_send()</function> and
 172     <function>sd_bus_send_to()</function> were added in version 246.</para>
 173   </refsect1>
 174
 175   <refsect1>
 176     <title>See Also</title>
 177
 178     <para><simplelist type="inline">
 179       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 180       <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 181       <member><citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 182       <member><citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 183       <member><citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 184       <member><citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 185     </simplelist></para>
 186   </refsect1>
 187
 188 </refentry>