diff --git a/man/rules/meson.build b/man/rules/meson.build index 9b2e102dd15..4bcb273810a 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -388,7 +388,7 @@ manpages = [ 'sd_bus_release_name_async', 'sd_bus_request_name_async'], ''], - ['sd_bus_send', '3', [], ''], + ['sd_bus_send', '3', ['sd_bus_send_to'], ''], ['sd_bus_set_address', '3', ['sd_bus_get_address', 'sd_bus_set_exec'], ''], ['sd_bus_set_close_on_exit', '3', ['sd_bus_get_close_on_exit'], ''], ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 590998941ad..c6ceef95fef 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -138,6 +138,7 @@ sd_bus_reply_method_error3, sd_bus_request_name3, sd_bus_send3, +sd_bus_send_to3, sd_bus_set_address3, sd_bus_set_allow_interactive_authorization3, sd_bus_set_bus_client3, diff --git a/man/sd_bus_send.xml b/man/sd_bus_send.xml index 659fa2a86ce..2cdf436db2b 100644 --- a/man/sd_bus_send.xml +++ b/man/sd_bus_send.xml @@ -18,6 +18,7 @@ sd_bus_send + sd_bus_send_to Queue a D-Bus message for transfer @@ -32,35 +33,48 @@ sd_bus_message *m uint64_t *cookie + + + int sd_bus_send_to + sd_bus *bus + sd_bus_message *m + const char *destination + uint64_t *cookie + Description - sd_bus_send() queues the bus message object m - for transfer. If bus is NULL, the bus that - m is attached to is used. bus 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 cookie is not - NULL, it is set to the message identifier. This value can later be used to - match incoming replies to their corresponding messages. If cookie is set - to NULL and the message is not sealed, sd_bus_send() - assumes the message m doesn't expect a reply and adds the necessary - headers to indicate this. + sd_bus_send() queues the bus message object m for + transfer. If bus is NULL, the bus that + m is attached to is used. bus 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 cookie is not NULL, it is set to the + message identifier. This value can later be used to match incoming replies to their corresponding + messages. If cookie is set to NULL and the message is not + sealed, sd_bus_send() assumes the message m doesn't expect a + reply and adds the necessary headers to indicate this. Note that in most scenarios, sd_bus_send() should not be called directly. Instead, use higher level functions such as sd_bus_call_method3 and sd_bus_reply_method_return3 which call sd_bus_send() internally. + + sd_bus_send_to() is a shorthand for sending a message to a specific + destination. It's main use case is to simplify sending unicast signal messages (signals that only have a + single receiver). It's behavior is similar to calling + sd_bus_message_set_destination3 + followed by calling sd_bus_send(). Return Value - On success, this function returns a non-negative integer. On failure, it returns a - negative errno-style error code. + On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code. Errors @@ -85,8 +99,8 @@ -ECHILD - The bus connection was allocated in a parent process and is being reused - in a child process after fork(). + The bus connection was allocated in a parent process and is being reused in a child + process after fork(). @@ -128,8 +142,7 @@ sd-bus3, sd_bus_call_method3, sd_bus_message_set_destination3, - sd_bus_reply_method_return3, - sd_bus_send_to3 + sd_bus_reply_method_return3