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+ -->
6 <refentry id=
"sd_bus_send"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_bus_send
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_bus_send
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_bus_send
</refname>
21 <refname>sd_bus_send_to
</refname>
23 <refpurpose>Queue a D-Bus message for transfer
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>
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>
48 <title>Description
</title>
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>
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>
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>
74 <title>Return Value
</title>
76 <para>On success, these functions return a non-negative integer. On failure, they return a negative
77 errno-style error code.
</para>
79 <refsect2 id='errors'
>
82 <para>Returned errors may indicate the following problems:
</para>
86 <term><constant>-EINVAL
</constant></term>
88 <listitem><para>The input parameter
<parameter>m
</parameter> is
<constant>NULL
</constant>.
93 <term><constant>-EOPNOTSUPP
</constant></term>
95 <listitem><para>The bus connection does not support sending file descriptors.
100 <term><constant>-ECHILD
</constant></term>
102 <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
103 process after
<function>fork()
</function>.
</para></listitem>
107 <term><constant>-ENOBUFS
</constant></term>
109 <listitem><para>The bus connection's write queue is full.
</para></listitem>
113 <term><constant>-ENOTCONN
</constant></term>
115 <listitem><para>The input parameter
<parameter>bus
</parameter> is
116 <constant>NULL
</constant> or the bus is not connected.
</para></listitem>
120 <term><constant>-ECONNRESET
</constant></term>
122 <listitem><para>The bus connection was closed while waiting for the response.
127 <term><constant>-ENOMEM
</constant></term>
129 <listitem><para>Memory allocation failed.
</para></listitem>
135 <xi:include href=
"libsystemd-pkgconfig.xml" />
138 <title>See Also
</title>
141 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
142 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
143 <citerefentry><refentrytitle>sd_bus_call_method
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
144 <citerefentry><refentrytitle>sd_bus_message_set_destination
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
145 <citerefentry><refentrytitle>sd_bus_reply_method_return
</refentrytitle><manvolnum>3</manvolnum></citerefentry>