on the same bus by using the peer's connection ID as the destination.
</para>
<para>
- The KDBUS_CMD_HELLO ioctl takes the following struct as argument.
+ The <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
+ kdbus_cmd_hello</type> as argument.
</para>
<programlisting>
<varlistentry>
<term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>comm</emphasis> of a task's
- <emphasis>TID</emphasis>, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>TID</emphasis> (thread ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>comm</emphasis> of a task's
- <emphasis>PID</emphasis>, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>PID</emphasis> (process ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>path to the executable</emphasis> of a
- task, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>path to the executable</emphasis> of a task,
+ stored as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size. Receivers of
+ this item should not use its contents for any kind of security
+ measures. See below.
</para></listitem>
</varlistentry>
<varname>new_id</varname> describes the new owner of the name and
is set to <constant>0</constant> values in case of
<constant>KDBUS_ITEM_NAME_REMOVE</constant>.
+ The <varname>name</varname> field contains the well-known name the
+ notification is about, as null-terminated string.
See
<citerefentry>
<refentrytitle>kdbus.match</refentrytitle>
<listitem>
<para>
By default, all calls to kdbus are considered asynchronous,
- non-blocking. However, as there are many use cases that need to wait
- for a remote peer to answer a method call, there's a way to send a
- message and wait for a reply in a synchronous fashion. This is what
- the KDBUS_SEND_SYNC_REPLY controls. The KDBUS_CMD_SEND ioctl will block
- until the reply has arrived, the timeout limit is reached, in case the
- remote connection was shut down, or if interrupted by a signal before
- any reply; see signal(7).
-
- The offset of the reply message in the sender's pool is stored in in
- 'offset_reply' when the ioctl has returned without error. Hence, there
- is no need for another KDBUS_CMD_RECV ioctl or anything else to receive
- the reply.
+ non-blocking. However, as there are many use cases that need
+ to wait for a remote peer to answer a method call, there's a
+ way to send a message and wait for a reply in a synchronous
+ fashion. This is what the
+ <constant>KDBUS_SEND_SYNC_REPLY</constant> controls. The
+ <constant>KDBUS_CMD_SEND</constant> ioctl will block until the
+ reply has arrived, the timeout limit is reached, in case the
+ remote connection was shut down, or if interrupted by a signal
+ before any reply; see
+ <citerefentry>
+ <refentrytitle>signal</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+
+ The offset of the reply message in the sender's pool is stored
+ in in <varname>offset_reply</varname> when the ioctl has
+ returned without error. Hence, there is no need for another
+ <constant>KDBUS_CMD_RECV</constant> ioctl or anything else to
+ receive the reply.
</para>
</listitem>
</varlistentry>
<title>Receiving messages</title>
<para>
- Messages are received by the client with the KDBUS_CMD_RECV ioctl.
- The endpoint file of the bus supports <emphasis>poll/epoll/select</emphasis>
- to wake up the receiving process when new messages are queued up to be received.
+ Messages are received by the client with the
+ <constant>KDBUS_CMD_RECV</constant> ioctl. The endpoint file of the bus
+ supports <function>poll()/epoll()/select()</function> to wake up the
+ receiving process when new messages are queued up to be received.
</para>
<para>
</para>
<itemizedlist mark='opencircle'>
- <listitem><para>kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant></para></listitem>
- <listitem><para>kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant></para></listitem>
- <listitem><para>kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant></para></listitem>
- <listitem><para>Has exactly one of the aforementioned items attached</para></listitem>
+ <listitem><para>
+ kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant>
+ </para></listitem>
+ <listitem>
+ <para>kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ Has exactly one of the aforementioned items attached
+ </para></listitem>
</itemizedlist>
<para>
- Kernel notifications have an item of type KDBUS_ITEM_TIMESTAMP attached.
+ Kernel notifications have an item of type
+ <constant>KDBUS_ITEM_TIMESTAMP</constant> attached.
</para>
<para>
<programlisting>
struct kdbus_cmd_name {
__u64 size;
- The overall size of this struct, including the null-terminated name string.
-
__u64 flags;
- Flags to the command. Currently unused and must be zero.
-
__u64 kernel_flags;
- Valid flags for this command, returned by the kernel upon each call.
-
__u64 return_flags;
- Flags returned by the kernel. Currently unused and always set to zero by
- the kernel.
-
struct kdbus_item items[0];
- Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is
- expected and allowed, and the contained string must be a valid bus name.
};
</programlisting>
<constant>KDBUS_ITEM_BLOOM_PARAMETER</constant> item that is returned by
<constant>KDBUS_CMD_HELLO</constant>. Internally, the pool is segmented
into <emphasis>slices</emphasis>, each referenced by its
- <emphasis>offset</emphasis> in the pool.
+ <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
</para>
<para>
<para>
Alternatively, instead of mapping the entire pool buffer, only parts
of it can be mapped. Every kdbus command that returns an
- <emphasis> offset</emphasis> (see above) also reports a
+ <emphasis>offset</emphasis> (see above) also reports a
<emphasis>size</emphasis> along with it, so userspace can be written
in a way that it only maps portions of the part to access a specific
<emphasis>slice</emphasis>.
counter-part blob, called a 'filter', and signals are only delivered to
peers which have a match that whitelists the message's filter. Senders
of signal messages can use either a single connection ID as receiver, or
- KDBUS_DST_ID_BROADCAST to potentially send it to all connections of a
- bus, following the logic described above. See
+ <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
+ all connections of a bus, following the logic described above. See
<citerefentry>
<refentrytitle>kdbus.match</refentrytitle>
<manvolnum>7</manvolnum>
projects / platform / core / system / kdbus-bus.git / commitdiff