summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.message.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kdbus/kdbus.message.xml')
-rw-r--r--Documentation/kdbus/kdbus.message.xml1277
1 files changed, 1277 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.message.xml b/Documentation/kdbus/kdbus.message.xml
new file mode 100644
index 00000000000..c25000dcfbc
--- /dev/null
+++ b/Documentation/kdbus/kdbus.message.xml
@@ -0,0 +1,1277 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus.message">
+
+ <refentryinfo>
+ <title>kdbus.message</title>
+ <productname>kdbus.message</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.message</refname>
+ <refpurpose>kdbus message</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A kdbus message is used to exchange information between two connections
+ on a bus, or to transport notifications from the kernel to one or many
+ connections. This document describes the layout of messages, how payload
+ is added to them and how they are sent and received.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Message layout</title>
+
+ <para>The layout of a message is shown below.</para>
+
+ <programlisting>
+ +-------------------------------------------------------------------------+
+ | Message |
+ | +---------------------------------------------------------------------+ |
+ | | Header | |
+ | | size: overall message size, including the data records | |
+ | | destination: connection ID of the receiver | |
+ | | source: connection ID of the sender (set by kernel) | |
+ | | payload_type: "DBusDBus" textual identifier stored as uint64_t | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | type: type of data | |
+ | | data: reference to data (address or file descriptor) | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size (without padding) | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | padding bytes to the next 8 byte alignment | |
+ | +---------------------------------------------------------------------+ |
+ | +---------------------------------------------------------------------+ |
+ | | Data Record | |
+ | | size: overall record size | |
+ | | ... | |
+ | +---------------------------------------------------------------------+ |
+ | ... further data records ... |
+ +-------------------------------------------------------------------------+
+ </programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Message payload</title>
+
+ <para>
+ When connecting to the bus, receivers request a memory pool of a given
+ size, large enough to carry all backlog of data enqueued for the
+ connection. The pool is internally backed by a shared memory file which
+ can be <function>mmap()</function>ed by the receiver. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ Message payload must be described in items attached to a message when
+ it is sent. A receiver can access the payload by looking at the items
+ that are attached to a message in its pool. The following items are used.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <listitem>
+ <para>
+ This item references a piece of memory on the sender side which is
+ directly copied into the receiver's pool. This way, two peers can
+ exchange data by effectively doing a single-copy from one process
+ to another; the kernel will not buffer the data anywhere else.
+ This item is never found in a message received by a connection.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem>
+ <para>
+ This item is attached to messages on the receiving side and points
+ to a memory area inside the receiver's pool. The
+ <varname>offset</varname> variable in the item denotes the memory
+ location relative to the message itself.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem>
+ <para>
+ Messages can reference <emphasis>memfd</emphasis> files which
+ contain the data. memfd files are tmpfs-backed files that allow
+ sealing of the content of the file, which prevents all writable
+ access to the file content.
+ </para>
+ <para>
+ Only memfds that have
+ <constant>(F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL)
+ </constant>
+ set are accepted as payload data, which enforces reliable passing of
+ data. The receiver can assume that neither the sender nor anyone
+ else can alter the content after the message is sent. If those
+ seals are not set on the memfd, the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will be
+ set to <constant>ETXTBUSY</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Messages can transport regular file descriptors via
+ <constant>KDBUS_ITEM_FDS</constant>. This item carries an array
+ of <type>int</type> values in <varname>item.fd</varname>. The
+ maximum number of file descriptors in the item is
+ <constant>253</constant>, and only one item of this type is
+ accepted per message. All passed values must be valid file
+ descriptors; the open count of each file descriptors is increased
+ by installing it to the receiver's task. This item can only be
+ used for directed messages, not for broadcasts, and only to
+ remote peers that have opted-in for receiving file descriptors
+ at connection time (<constant>KDBUS_HELLO_ACCEPT_FD</constant>).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The sender must not make any assumptions on the type in which data is
+ received by the remote peer. The kernel is free to re-pack multiple
+ <constant>KDBUS_ITEM_PAYLOAD_VEC</constant> and
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> payloads. For instance, the
+ kernel may decide to merge multiple <constant>VECs</constant> into a
+ single <constant>VEC</constant>, inline <constant>MEMFD</constant>
+ payloads into memory, or merge all passed <constant>VECs</constant> into a
+ single <constant>MEMFD</constant>. However, the kernel preserves the order
+ of passed data. This means that the order of all <constant>VEC</constant>
+ and <constant>MEMFD</constant> items is not changed in respect to each
+ other. In other words: All passed <constant>VEC</constant> and
+ <constant>MEMFD</constant> data payloads are treated as a single stream
+ of data that may be received by the remote peer in a different set of
+ chunks than it was sent as.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Sending messages</title>
+
+ <para>
+ Messages are passed to the kernel with the
+ <constant>KDBUS_CMD_SEND</constant> ioctl. Depending on the destination
+ address of the message, the kernel delivers the message to the specific
+ destination connection, or to some subset of all connections on the same
+ bus. Sending messages across buses is not possible. Messages are always
+ queued in the memory pool of the destination connection (see above).
+ </para>
+
+ <para>
+ The <constant>KDBUS_CMD_SEND</constant> ioctl uses a
+ <type>struct kdbus_cmd_send</type> to describe the message
+ transfer.
+ </para>
+ <programlisting>
+struct kdbus_cmd_send {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __u64 msg_address;
+ struct kdbus_msg_info reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags for message delivery</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_SEND_SYNC_REPLY</constant></term>
+ <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
+ <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>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ <constant>0</constant> by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_address</varname></term>
+ <listitem><para>
+ In this field, users have to provide a pointer to a message
+ (<type>struct kdbus_msg</type>) to send. See below for a
+ detailed description.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>reply</varname></term>
+ <listitem><para>
+ Only used for synchronous replies. See description of
+ <type>struct kdbus_cmd_recv</type> for more details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are currently recognized.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem>
+ <para>
+ When this optional item is passed in, and the call is
+ executed as SYNC call, the passed in file descriptor can be
+ used as alternative cancellation point. The kernel will call
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ on this file descriptor, and once it reports any incoming
+ bytes, the blocking send operation will be canceled; the
+ blocking, synchronous ioctl call will return
+ <errorcode>-1</errorcode>, and <varname>errno</varname> will
+ be set to <errorname>ECANCELED</errorname>.
+ Any type of file descriptor on which
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ can be called on can be used as payload to this item; for
+ example, an eventfd can be used for this purpose, see
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ For asynchronous message sending, this item is allowed but
+ ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The fields in this struct are described below.
+ The message referenced the <varname>msg_address</varname> above has
+ the following layout.
+ </para>
+
+ <programlisting>
+struct kdbus_msg {
+ __u64 size;
+ __u64 flags;
+ __s64 priority;
+ __u64 dst_id;
+ __u64 src_id;
+ __u64 payload_type;
+ __u64 cookie;
+ __u64 timeout_ns;
+ __u64 cookie_reply;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to describe message details.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_MSG_EXPECT_REPLY</constant></term>
+ <listitem>
+ <para>
+ Expect a reply to this message from the remote peer. With
+ this bit set, the timeout_ns field must be set to a non-zero
+ number of nanoseconds in which the receiving peer is expected
+ to reply. If such a reply is not received in time, the sender
+ will be notified with a timeout message (see below). The
+ value must be an absolute value, in nanoseconds and based on
+ <constant>CLOCK_MONOTONIC</constant>.
+ </para><para>
+ For a message to be accepted as reply, it must be a direct
+ message to the original sender (not a broadcast and not a
+ signal message), and its
+ <varname>kdbus_msg.reply_cookie</varname> must match the
+ previous message's <varname>kdbus_msg.cookie</varname>.
+ </para><para>
+ Expected replies also temporarily open the policy of the
+ sending connection, so the other peer is allowed to respond
+ within the given time window.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_MSG_NO_AUTO_START</constant></term>
+ <listitem>
+ <para>
+ By default, when a message is sent to an activator
+ connection, the activator is notified and will start an
+ implementer. This flag inhibits that behavior. With this bit
+ set, and the remote being an activator, the ioctl will fail
+ with <varname>errno</varname> set to
+ <constant>EADDRNOTAVAIL</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Requests a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will return
+ <errorcode>0</errorcode>, and the <varname>flags</varname>
+ field will have all bits set that are valid for this command.
+ The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
+ cleared by the operation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ The priority of this message. Receiving messages (see below) may
+ optionally be constrained to messages of a minimal priority. This
+ allows for use cases where timing critical data is interleaved with
+ control data on the same connection. If unused, the priority field
+ should be set to <constant>0</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dst_id</varname></term>
+ <listitem><para>
+ The numeric ID of the destination connection, or
+ <constant>KDBUS_DST_ID_BROADCAST</constant>
+ (~0ULL) to address every peer on the bus, or
+ <constant>KDBUS_DST_ID_NAME</constant> (0) to look
+ it up dynamically from the bus' name registry.
+ In the latter case, an item of type
+ <constant>KDBUS_ITEM_DST_NAME</constant> is mandatory.
+ Also see
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>src_id</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this member will contain the sending
+ connection's numerical ID. Should be 0 at send time.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>payload_type</varname></term>
+ <listitem><para>
+ Type of the payload in the actual data records. Currently, only
+ <constant>KDBUS_PAYLOAD_DBUS</constant> is accepted as input value
+ of this field. When receiving messages that are generated by the
+ kernel (notifications), this field will contain
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie</varname></term>
+ <listitem><para>
+ Cookie of this message, for later recognition. Also, when replying
+ to a message (see above), the <varname>cookie_reply</varname>
+ field must match this value.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>timeout_ns</varname></term>
+ <listitem><para>
+ If the message sent requires a reply from the remote peer (see above),
+ this field contains the timeout in absolute nanoseconds based on
+ <constant>CLOCK_MONOTONIC</constant>. Also see
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>cookie_reply</varname></term>
+ <listitem><para>
+ If the message sent is a reply to another message, this field must
+ match the cookie of the formerly received message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ A dynamically sized list of items to contain additional information.
+ The following items are expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem>
+ <para>
+ Actual data records containing the payload. See section
+ "Passing of Payload Data".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem>
+ <para>
+ Bloom filter for matches (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem>
+ <para>
+ Well-known name to send this message to. Required if
+ <varname>dst_id</varname> is set to
+ <constant>KDBUS_DST_ID_NAME</constant>.
+ If a connection holding the given name can't be found,
+ the ioctl will fail with <varname>errno</varname> set to
+ <constant>ESRCH</constant> is returned.
+ </para>
+ <para>
+ For messages to a unique name (ID), this item is optional. If
+ present, the kernel will make sure the name owner matches the
+ given unique name. This allows programs to tie the message
+ sending to the condition that a name is currently owned by a
+ certain unique name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The message will be augmented by the requested metadata items when
+ queued into the receiver's pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on metadata.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Receiving messages</title>
+
+ <para>
+ 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>; when new messages
+ are available on the connection's file descriptor,
+ <constant>POLLIN</constant> is reported. For compatibility reasons,
+ <constant>POLLOUT</constant> is always reported as well. Note, however,
+ that the latter does not guarantee that a message can in fact be sent, as
+ this depends on how many pending messages the receiver has in its pool.
+ </para>
+
+ <para>
+ With the <constant>KDBUS_CMD_RECV</constant> ioctl, a
+ <type>struct kdbus_cmd_recv</type> is used.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_recv {
+ __u64 size;
+ __u64 flags;
+ __u64 return_flags;
+ __s64 priority;
+ __u64 dropped_msgs;
+ struct kdbus_msg_info msg;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>Flags to control the receive command.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_PEEK</constant></term>
+ <listitem>
+ <para>
+ Just return the location of the next message. Do not install
+ file descriptors or anything else. This is usually used to
+ determine the sender of the next queued message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_DROP</constant></term>
+ <listitem>
+ <para>
+ Drop the next message without doing anything else with it,
+ and free the pool slice. This a short-cut for
+ <constant>KDBUS_RECV_PEEK</constant> and
+ <constant>KDBUS_CMD_FREE</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_RECV_USE_PRIORITY</constant></term>
+ <listitem>
+ <para>
+ Dequeue the messages ordered by their priority, and filtering
+ them with the priority field (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ valid for this command.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. If the <varname>dropped_msgs</varname>
+ field is non-zero, <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant>
+ is set. If a file descriptor could not be installed, the
+ <constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant> flag is set.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ With <constant>KDBUS_RECV_USE_PRIORITY</constant> set in
+ <varname>flags</varname>, messages will be dequeued ordered by their
+ priority, starting with the highest value. Also, messages will be
+ filtered by the value given in this field, so the returned message
+ will at least have the requested priority. If no such message is
+ waiting in the queue, the ioctl will fail, and
+ <varname>errno</varname> will be set to <constant>EAGAIN</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dropped_msgs</varname></term>
+ <listitem><para>
+ Whenever a message with <constant>KDBUS_MSG_SIGNAL</constant> is sent
+ but cannot be queued on a peer (e.g., as it contains FDs but the peer
+ does not support FDs, or there is no space left in the peer's pool..)
+ the 'dropped_msgs' counter of the peer is incremented. On the next
+ RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct
+ and cleared on the peer. If it was non-zero, the
+ <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant> flag will be set
+ in <varname>return_flags</varname>. Note that this will only happen
+ if the ioctl succeeded or failed with <constant>EAGAIN</constant>. In
+ other error cases, the 'dropped_msgs' field of the peer is left
+ untouched.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg</varname></term>
+ <listitem><para>
+ Embedded struct containing information on the received message when
+ this command succeeded (see below).
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused, and all items will be rejected with
+ <varname>errno</varname> set to <constant>EINVAL</constant>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Both <type>struct kdbus_cmd_recv</type> and
+ <type>struct kdbus_cmd_send</type> embed
+ <type>struct kdbus_msg_info</type>.
+ For the <constant>KDBUS_CMD_SEND</constant> ioctl, it is used to catch
+ synchronous replies, if one was requested, and is unused otherwise.
+ </para>
+
+ <programlisting>
+struct kdbus_msg_info {
+ __u64 offset;
+ __u64 msg_size;
+ __u64 return_flags;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ Upon return of the ioctl, this field contains the offset in the
+ receiver's memory pool. The memory must be freed with
+ <constant>KDBUS_CMD_FREE</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_size</varname></term>
+ <listitem><para>
+ Upon successful return of the ioctl, this field contains the size of
+ the allocated slice at offset <varname>offset</varname>.
+ It is the combination of the size of the stored
+ <type>struct kdbus_msg</type> object plus all appended VECs.
+ You can use it in combination with <varname>offset</varname> to map
+ a single message, instead of mapping the entire pool. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for further details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem>
+ <para>
+ Kernel-provided return flags. Currently, the following flags are
+ defined.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant></term>
+ <listitem>
+ <para>
+ The message contained memfds or file descriptors, and the
+ kernel failed to install one or more of them at receive time.
+ Most probably that happened because the maximum number of
+ file descriptors for the receiver's task were exceeded.
+ In such cases, the message is still delivered, so this is not
+ a fatal condition. File descriptors numbers inside the
+ <constant>KDBUS_ITEM_FDS</constant> item or memfd files
+ referenced by <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant>
+ items which could not be installed will be set to
+ <constant>-1</constant>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unless <constant>KDBUS_RECV_DROP</constant> was passed, the
+ <varname>offset</varname> field contains the location of the new message
+ inside the receiver's pool after the <constant>KDBUS_CMD_RECV</constant>
+ ioctl was employed. The message is stored as <type>struct kdbus_msg</type>
+ at this offset, and can be interpreted with the semantics described above.
+ </para>
+ <para>
+ Also, if the connection allowed for file descriptor to be passed
+ (<constant>KDBUS_HELLO_ACCEPT_FD</constant>), and if the message contained
+ any, they will be installed into the receiving process when the
+ <constant>KDBUS_CMD_RECV</constant> ioctl is called.
+ <emphasis>memfds</emphasis> may always be part of the message payload.
+ The receiving task is obliged to close all file descriptors appropriately
+ once no longer needed. If <constant>KDBUS_RECV_PEEK</constant> is set, no
+ file descriptors are installed. This allows for peeking at a message,
+ looking at its metadata only and dropping it via
+ <constant>KDBUS_RECV_DROP</constant>, without installing any of the file
+ descriptors into the receiving process.
+ </para>
+ <para>
+ The caller is obliged to call the <constant>KDBUS_CMD_FREE</constant>
+ ioctl with the returned offset when the memory is no longer needed.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Notifications</title>
+ <para>
+ A kernel notification is a regular kdbus message with the following
+ details.
+ </para>
+
+ <itemizedlist>
+ <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 items attached that are described below.
+ </para></listitem>
+ <listitem><para>
+ Always has a timestamp item (<constant>KDBUS_ITEM_TIMESTAMP</constant>)
+ attached.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ The kernel will notify its users of the following events.
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ When connection <emphasis>A</emphasis> is terminated while connection
+ <emphasis>B</emphasis> is waiting for a reply from it, connection
+ <emphasis>B</emphasis> is notified with a message with an item of
+ type <constant>KDBUS_ITEM_REPLY_DEAD</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When connection <emphasis>A</emphasis> does not receive a reply from
+ connection <emphasis>B</emphasis> within the specified timeout window,
+ connection <emphasis>A</emphasis> will receive a message with an
+ item of type <constant>KDBUS_ITEM_REPLY_TIMEOUT</constant>.
+ </para></listitem>
+
+ <listitem><para>
+ When an ordinary connection (not a monitor) is created on or removed
+ from a bus, messages with an item of type
+ <constant>KDBUS_ITEM_ID_ADD</constant> or
+ <constant>KDBUS_ITEM_ID_REMOVE</constant>, respectively, are delivered
+ to all bus members that match these messages through their match
+ database. Eavesdroppers (monitor connections) do not cause such
+ notifications to be sent. They are invisible on the bus.
+ </para></listitem>
+
+ <listitem><para>
+ When a connection gains or loses ownership of a name, messages with an
+ item of type <constant>KDBUS_ITEM_NAME_ADD</constant>,
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant> or
+ <constant>KDBUS_ITEM_NAME_CHANGE</constant> are delivered to all bus
+ members that match these messages through their match database.
+ </para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
+ on error, <errorcode>-1</errorcode> is returned, and
+ <varname>errno</varname> is set to indicate the error.
+ If the issued ioctl is illegal for the file descriptor used,
+ <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
+ </para>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_SEND</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors in <constant>KDBUS_ITEM_FDS</constant> item are
+ either kdbus handles or unix domain sockets. Both are currently
+ unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ The submitted payload type is
+ <constant>KDBUS_PAYLOAD_KERNEL</constant>,
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set without timeout
+ or cookie values, <constant>KDBUS_SEND_SYNC_REPLY</constant> was
+ set without <constant>KDBUS_MSG_EXPECT_REPLY</constant>, an invalid
+ item was supplied, <constant>src_id</constant> was non-zero and was
+ different from the current connection's ID, a supplied memfd had a
+ size of 0, or a string was not properly null-terminated.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOTUNIQ</constant></term>
+ <listitem><para>
+ The supplied destination is
+ <constant>KDBUS_DST_ID_BROADCAST</constant> and either
+ file descriptors were passed, or
+ <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set,
+ or a timeout was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ Too many items
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMSGSIZE</constant></term>
+ <listitem><para>
+ The size of the message header and items or the payload vector
+ is excessive.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ Multiple <constant>KDBUS_ITEM_FDS</constant>,
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant> or
+ <constant>KDBUS_ITEM_DST_NAME</constant> items were supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADF</constant></term>
+ <listitem><para>
+ The supplied <constant>KDBUS_ITEM_FDS</constant> or
+ <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> items
+ contained an illegal file descriptor.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMEDIUMTYPE</constant></term>
+ <listitem><para>
+ The supplied memfd is not a sealed kdbus memfd.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EMFILE</constant></term>
+ <listitem><para>
+ Too many file descriptors inside a
+ <constant>KDBUS_ITEM_FDS</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EBADMSG</constant></term>
+ <listitem><para>
+ An item had illegal size, both a <constant>dst_id</constant> and a
+ <constant>KDBUS_ITEM_DST_NAME</constant> was given, or both a name
+ and a bloom filter was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETXTBSY</constant></term>
+ <listitem><para>
+ The supplied kdbus memfd file cannot be sealed or the seal
+ was removed, because it is shared with other processes or
+ still mapped with
+ <citerefentry>
+ <refentrytitle>mmap</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECOMM</constant></term>
+ <listitem><para>
+ A peer does not accept the file descriptors addressed to it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EFAULT</constant></term>
+ <listitem><para>
+ The supplied bloom filter size was not 64-bit aligned, or supplied
+ memory could not be accessed by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDOM</constant></term>
+ <listitem><para>
+ The supplied bloom filter size did not match the bloom filter
+ size of the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EDESTADDRREQ</constant></term>
+ <listitem><para>
+ <constant>dst_id</constant> was set to
+ <constant>KDBUS_DST_ID_NAME</constant>, but no
+ <constant>KDBUS_ITEM_DST_NAME</constant> was attached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ The name to look up was not found in the name registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRNOTAVAIL</constant></term>
+ <listitem><para>
+ <constant>KDBUS_MSG_NO_AUTO_START</constant> was given but the
+ destination connection is an activator.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENXIO</constant></term>
+ <listitem><para>
+ The passed numeric destination connection ID couldn't be found,
+ or is not connected.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ECONNRESET</constant></term>
+ <listitem><para>
+ The destination connection is no longer active.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ETIMEDOUT</constant></term>
+ <listitem><para>
+ Timeout while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINTR</constant></term>
+ <listitem><para>
+ Interrupted system call while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPIPE</constant></term>
+ <listitem><para>
+ When sending a message, a synchronous reply from the receiving
+ connection was expected but the connection died before answering.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ Too many pending messages on the receiver side.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMCHG</constant></term>
+ <listitem><para>
+ Both a well-known name and a unique name (ID) was given, but
+ the name is not currently owned by that connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EXFULL</constant></term>
+ <listitem><para>
+ The memory pool of the receiver is full.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EREMOTEIO</constant></term>
+ <listitem><para>
+ While synchronously waiting for a reply, the remote peer
+ failed with an I/O error.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_RECV</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EOPNOTSUPP</constant></term>
+ <listitem><para>
+ The connection is not an ordinary connection, or the passed
+ file descriptors are either kdbus handles or unix domain
+ sockets. Both are currently unsupported.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid flags or offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EAGAIN</constant></term>
+ <listitem><para>
+ No message found in the queue
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>clock_gettime</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>ioctl</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>poll</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>select</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>epoll</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>eventfd</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+</refentry>