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>
22 <refpurpose>Queue a D-Bus message for transfer
</refpurpose>
27 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
30 <funcdef>int
<function>sd_bus_send
</function></funcdef>
31 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
32 <paramdef>sd_bus_message *
<parameter>m
</parameter></paramdef>
33 <paramdef>uint64_t *
<parameter>cookie
</parameter></paramdef>
39 <title>Description
</title>
41 <para><function>sd_bus_send()
</function> queues the bus message object
<parameter>m
</parameter>
42 for transfer. If
<parameter>bus
</parameter> is
<constant>NULL
</constant>, the bus that
43 <parameter>m
</parameter> is attached to is used.
<parameter>bus
</parameter> only needs to be set
44 when the message is sent to a different bus than the one it's attached to, for example when
45 forwarding messages. If the output parameter
<parameter>cookie
</parameter> is not
46 <constant>NULL
</constant>, it is set to the message identifier. This value can later be used to
47 match incoming replies to their corresponding messages. If
<parameter>cookie
</parameter> is set
48 to
<constant>NULL
</constant> and the message is not sealed,
<function>sd_bus_send()
</function>
49 assumes the message
<parameter>m
</parameter> doesn't expect a reply and adds the necessary
50 headers to indicate this.
</para>
52 <para>Note that in most scenarios,
<function>sd_bus_send()
</function> should not be called
53 directly. Instead, use higher level functions such as
54 <citerefentry><refentrytitle>sd_bus_call_method
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
55 <citerefentry><refentrytitle>sd_bus_reply_method_return
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
56 which call
<function>sd_bus_send()
</function> internally.
</para>
60 <title>Return Value
</title>
62 <para>On success, this function returns a non-negative integer. On failure, it returns a
63 negative errno-style error code.
</para>
65 <refsect2 id='errors'
>
68 <para>Returned errors may indicate the following problems:
</para>
72 <term><constant>-EINVAL
</constant></term>
74 <listitem><para>The input parameter
<parameter>m
</parameter> is
<constant>NULL
</constant>.
79 <term><constant>-EOPNOTSUPP
</constant></term>
81 <listitem><para>The bus connection does not support sending file descriptors.
86 <term><constant>-ECHILD
</constant></term>
88 <listitem><para>The bus connection was allocated in a parent process and is being reused
89 in a child process after
<function>fork()
</function>.
</para></listitem>
93 <term><constant>-ENOBUFS
</constant></term>
95 <listitem><para>The bus connection's write queue is full.
</para></listitem>
99 <term><constant>-ENOTCONN
</constant></term>
101 <listitem><para>The input parameter
<parameter>bus
</parameter> is
102 <constant>NULL
</constant> or the bus is not connected.
</para></listitem>
106 <term><constant>-ECONNRESET
</constant></term>
108 <listitem><para>The bus connection was closed while waiting for the response.
113 <term><constant>-ENOMEM
</constant></term>
115 <listitem><para>Memory allocation failed.
</para></listitem>
121 <xi:include href=
"libsystemd-pkgconfig.xml" />
124 <title>See Also
</title>
127 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
128 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
129 <citerefentry><refentrytitle>sd_bus_call_method
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
130 <citerefentry><refentrytitle>sd_bus_message_set_destination
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
131 <citerefentry><refentrytitle>sd_bus_reply_method_return
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
132 <citerefentry><refentrytitle>sd_bus_send_to
</refentrytitle><manvolnum>3</manvolnum></citerefentry>