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.2/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
  23     <refpurpose>Queue a D-Bus message for transfer</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv>
  27     <funcsynopsis>
  28       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  29
  30       <funcprototype>
  31         <funcdef>int <function>sd_bus_send</function></funcdef>
  32         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  33         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  34         <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
  35       </funcprototype>
  36
  37       <funcprototype>
  38         <funcdef>int <function>sd_bus_send_to</function></funcdef>
  39         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  40         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  41         <paramdef>const char *<parameter>destination</parameter></paramdef>
  42         <paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
  43       </funcprototype>
  44     </funcsynopsis>
  45   </refsynopsisdiv>
  46
  47   <refsect1>
  48     <title>Description</title>
  49
  50     <para><function>sd_bus_send()</function> queues the bus message object <parameter>m</parameter> for
  51     transfer. If <parameter>bus</parameter> is <constant>NULL</constant>, the bus that
  52     <parameter>m</parameter> is attached to is used. <parameter>bus</parameter> only needs to be set when the
  53     message is sent to a different bus than the one it's attached to, for example when forwarding messages.
  54     If the output parameter <parameter>cookie</parameter> is not <constant>NULL</constant>, it is set to the
  55     message identifier. This value can later be used to match incoming replies to their corresponding
  56     messages. If <parameter>cookie</parameter> is set to <constant>NULL</constant> and the message is not
  57     sealed, <function>sd_bus_send()</function> assumes the message <parameter>m</parameter> doesn't expect a
  58     reply and adds the necessary headers to indicate this.</para>
  59
  60     <para>Note that in most scenarios, <function>sd_bus_send()</function> should not be called
  61     directly. Instead, use higher level functions such as
  62     <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
  63     <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  64     which call <function>sd_bus_send()</function> internally.</para>
  65
  66     <para><function>sd_bus_send_to()</function> is a shorthand for sending a message to a specific
  67     destination. It's main use case is to simplify sending unicast signal messages (signals that only have a
  68     single receiver). It's behavior is similar to calling
  69     <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  70     followed by calling <function>sd_bus_send()</function>.</para>
  71
  72     <para><function>sd_bus_send()</function>/<function>sd_bus_send_to()</function> will write the message
  73     directly to the underlying transport (e.g. kernel socket buffer) if possible. If the connection is not
  74     set up fully yet the message is queued locally. If the transport buffers are congested any unwritten
  75     message data is queued locally, too. If the connection has been closed or is currently being closed the
  76     call fails.
  77     <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> should
  78     be invoked to write out any queued message data to the transport.</para>
  79   </refsect1>
  80
  81   <refsect1>
  82     <title>Return Value</title>
  83
  84     <para>On success, these functions return a non-negative integer. On failure, they return a negative
  85     errno-style error code.</para>
  86
  87     <refsect2 id='errors'>
  88       <title>Errors</title>
  89
  90       <para>Returned errors may indicate the following problems:</para>
  91
  92       <variablelist>
  93         <varlistentry>
  94           <term><constant>-EINVAL</constant></term>
  95
  96           <listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
  97           </para></listitem>
  98         </varlistentry>
  99
 100         <varlistentry>
 101           <term><constant>-EOPNOTSUPP</constant></term>
 102
 103           <listitem><para>The bus connection does not support sending file descriptors.
 104           </para></listitem>
 105         </varlistentry>
 106
 107         <varlistentry>
 108           <term><constant>-ECHILD</constant></term>
 109
 110           <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
 111           process after <function>fork()</function>.</para></listitem>
 112         </varlistentry>
 113
 114         <varlistentry>
 115           <term><constant>-ENOBUFS</constant></term>
 116
 117           <listitem><para>The bus connection's write queue is full.</para></listitem>
 118         </varlistentry>
 119
 120         <varlistentry>
 121           <term><constant>-ENOTCONN</constant></term>
 122
 123           <listitem><para>The input parameter <parameter>bus</parameter> is
 124           <constant>NULL</constant> or the bus is not connected.</para></listitem>
 125         </varlistentry>
 126
 127         <varlistentry>
 128           <term><constant>-ECONNRESET</constant></term>
 129
 130           <listitem><para>The bus connection was closed while waiting for the response.
 131           </para></listitem>
 132         </varlistentry>
 133
 134         <varlistentry>
 135           <term><constant>-ENOMEM</constant></term>
 136
 137           <listitem><para>Memory allocation failed.</para></listitem>
 138         </varlistentry>
 139       </variablelist>
 140     </refsect2>
 141   </refsect1>
 142
 143   <xi:include href="libsystemd-pkgconfig.xml" />
 144
 145   <refsect1>
 146     <title>See Also</title>
 147
 148     <para>
 149       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 155     </para>
 156   </refsect1>
 157
 158 </refentry>