1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="sd_bus_send"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_send</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_send</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_send</refname>
<refpurpose>Queue a D-Bus message for transfer</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_send</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>uint64_t *<parameter>cookie</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_send()</function> queues the bus message object <parameter>m</parameter>
for transfer. If <parameter>bus</parameter> is <constant>NULL</constant>, the bus that
<parameter>m</parameter> is attached to is used. <parameter>bus</parameter> only needs to be set
when the message is sent to a different bus than the one it's attached to, for example when
forwarding messages. If the output parameter <parameter>cookie</parameter> is not
<constant>NULL</constant>, it is set to the message identifier. This value can later be used to
match incoming replies to their corresponding messages. If <parameter>cookie</parameter> is set
to <constant>NULL</constant> and the message is not sealed, <function>sd_bus_send()</function>
assumes the message <parameter>m</parameter> doesn't expect a reply and adds the necessary
headers to indicate this.</para>
<para>Note that in most scenarios, <function>sd_bus_send()</function> should not be called
directly. Instead, use higher level functions such as
<citerefentry><refentrytitle>sd_bus_call_method</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
<citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>
which call <function>sd_bus_send()</function> internally.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, this function returns a non-negative integer. On failure, it returns a
negative errno-style error code.</para>
<refsect2 id='errors'>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>The input parameter <parameter>m</parameter> is <constant>NULL</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EOPNOTSUPP</constant></term>
<listitem><para>The bus connection does not support sending file descriptors.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection was allocated in a parent process and is being reused
in a child process after <function>fork()</function>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOBUFS</constant></term>
<listitem><para>The bus connection's write queue is full.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOTCONN</constant></term>
<listitem><para>The input parameter <parameter>bus</parameter> is
<constant>NULL</constant> or the bus is not connected.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECONNRESET</constant></term>
<listitem><para>The bus connection was closed while waiting for the response.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<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_send_to</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
|
