diff options
author | Daan De Meyer <daan.j.demeyer@gmail.com> | 2020-04-23 20:40:30 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-23 22:38:44 +0200 |
commit | d7fbc6804e76fadfdf0cf1b0567eefae6778f1a6 (patch) | |
tree | 5dd2c83400879219b34641c14fbd154c71242073 /man/sd_bus_send.xml | |
parent | bf39cb7b922fd78e67a6db0c9d59c883808e861f (diff) | |
download | systemd-d7fbc6804e76fadfdf0cf1b0567eefae6778f1a6.tar.gz |
sd-bus: Add sd_bus_send_to docs
Diffstat (limited to 'man/sd_bus_send.xml')
-rw-r--r-- | man/sd_bus_send.xml | 45 |
1 files changed, 29 insertions, 16 deletions
diff --git a/man/sd_bus_send.xml b/man/sd_bus_send.xml index 659fa2a86c..2cdf436db2 100644 --- a/man/sd_bus_send.xml +++ b/man/sd_bus_send.xml @@ -18,6 +18,7 @@ <refnamediv> <refname>sd_bus_send</refname> + <refname>sd_bus_send_to</refname> <refpurpose>Queue a D-Bus message for transfer</refpurpose> </refnamediv> @@ -32,35 +33,48 @@ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> <paramdef>uint64_t *<parameter>cookie</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_send_to</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>const char *<parameter>destination</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><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> + + <para><function>sd_bus_send_to()</function> 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 + <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry> + followed by calling <function>sd_bus_send()</function>.</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> + <para>On success, these functions return a non-negative integer. On failure, they return a negative + errno-style error code.</para> <refsect2 id='errors'> <title>Errors</title> @@ -85,8 +99,8 @@ <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> + <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> @@ -128,8 +142,7 @@ <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> + <citerefentry><refentrytitle>sd_bus_reply_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> |