1SD_BUS_SEND(3)                    sd_bus_send                   SD_BUS_SEND(3)
2
3
4

NAME

6       sd_bus_send, sd_bus_send_to - Queue a D-Bus message for transfer
7

SYNOPSIS

9       #include <systemd/sd-bus.h>
10
11       int sd_bus_send(sd_bus *bus, sd_bus_message *m, uint64_t *cookie);
12
13       int sd_bus_send_to(sd_bus *bus, sd_bus_message *m,
14                          const char *destination, uint64_t *cookie);
15

DESCRIPTION

17       sd_bus_send() queues the bus message object m for transfer. If bus is
18       NULL, the bus that m is attached to is used.  bus only needs to be set
19       when the message is sent to a different bus than the one it's attached
20       to, for example when forwarding messages. If the output parameter
21       cookie is not NULL, it is set to the message identifier. This value can
22       later be used to match incoming replies to their corresponding
23       messages. If cookie is set to NULL and the message is not sealed,
24       sd_bus_send() assumes the message m doesn't expect a reply and adds the
25       necessary headers to indicate this.
26
27       Note that in most scenarios, sd_bus_send() should not be called
28       directly. Instead, use higher level functions such as
29       sd_bus_call_method(3) and sd_bus_reply_method_return(3) which call
30       sd_bus_send() internally.
31
32       sd_bus_send_to() is a shorthand for sending a message to a specific
33       destination. It's main use case is to simplify sending unicast signal
34       messages (signals that only have a single receiver). It's behavior is
35       similar to calling sd_bus_message_set_destination(3) followed by
36       calling sd_bus_send().
37
38       sd_bus_send()/sd_bus_send_to() will write the message directly to the
39       underlying transport (e.g. kernel socket buffer) if possible. If the
40       connection is not set up fully yet the message is queued locally. If
41       the transport buffers are congested any unwritten message data is
42       queued locally, too. If the connection has been closed or is currently
43       being closed the call fails.  sd_bus_process(3) should be invoked to
44       write out any queued message data to the transport.
45

RETURN VALUE

47       On success, these functions return a non-negative integer. On failure,
48       they return a negative errno-style error code.
49
50   Errors
51       Returned errors may indicate the following problems:
52
53       -EINVAL
54           The input parameter m is NULL.
55
56       -EOPNOTSUPP
57           The bus connection does not support sending file descriptors.
58
59       -ECHILD
60           The bus connection was allocated in a parent process and is being
61           reused in a child process after fork().
62
63       -ENOBUFS
64           The bus connection's write queue is full.
65
66       -ENOTCONN
67           The input parameter bus is NULL or the bus is not connected.
68
69       -ECONNRESET
70           The bus connection was closed while waiting for the response.
71
72       -ENOMEM
73           Memory allocation failed.
74

NOTES

76       These APIs are implemented as a shared library, which can be compiled
77       and linked to with the libsystemd pkg-config(1) file.
78

SEE ALSO

80       systemd(1), sd-bus(3), sd_bus_call_method(3),
81       sd_bus_message_set_destination(3), sd_bus_reply_method_return(3),
82       sd_bus_process(3)
83
84
85
86systemd 246                                                     SD_BUS_SEND(3)
Impressum