This is work in progress and not finished yet.
Signed-off-by: Daniel Mack <daniel@zonque.org>
tags
tools/kdbus-monitor
test/kdbus-test
+doc/html
+doc/man
check:
test/kdbus-test
-doc:
+mandoc:
+ $(MAKE) -C doc mandoc
+
+doc: mandoc
+
+kerneldoc_check:
$(KERNELDIR)/scripts/kernel-doc *.c kdbus.h >/dev/null | grep "^Warning"
install: module
--- /dev/null
+*.7
+manpage.*
+*.proc
--- /dev/null
+docs= \
+ kdbus.xml \
+ kdbus.bus.xml \
+ kdbus.connection.xml \
+ kdbus.endpoint.xml \
+ kdbus.fs.xml \
+ kdbus.item.xml \
+ kdbus.message.xml \
+ kdbus.names.xml \
+ kdbus.pool.xml
+
+manpages=$(docs:.xml=.7)
+
+%.7: %.xml
+ xmlto man -m stylesheet.xsl -o . $<
+
+mandoc: $(manpages)
+
--- /dev/null
+<?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.bus">
+
+ <refentryinfo>
+ <title>kdbus.bus</title>
+ <productname>kdbus.bus</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.bus</refname>
+ <refpurpose>kdbus bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ A bus is a resource that is shared between connections in order to transmit
+ messages (see <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ Each bus is independent and operations on the bus will not have any
+ effect on other buses. A bus is a management entity, that controls the
+ addresses of its connections, their policies and message transactions performed
+ via this bus.
+ </para>
+ <para>
+ Each bus is bound to the mount instance it was created on. It has a custom name that is
+ unique across all buses of a domain. In
+ <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+ a bus is presented as a directory. No operations can be performed on
+ the bus itself; instead you need to perform the operations on an endpoint
+ associated with the bus. Endpoints are accessible as files underneath the
+ bus directory. A default endpoint called "bus" is provided on each bus.
+ </para>
+ <para>
+ Bus names may be chosen freely except for one restriction: the name
+ must be prefixed with the numeric effective UID of the creator and a dash. This
+ is required to avoid namespace clashes between different users. When creating a
+ bus, that name that is passed in must be properly formatted, or the kernel will
+ refuse creation of the bus. Example: "1047-foobar" is an acceptable name for a
+ bus registered by a user with UID 1047. However, "1024-foobar" is not, and
+ neither is "foobar". The UID must be provided in the user-namespace of the
+ parent domain.
+ </para>
+ <para>
+ To create a new bus, you need to open the control file of a domain and employ
+ the <varname>KDBUS_CMD_BUS_MAKE</varname> ioctl. The control file descriptor that was used to issue
+ KDBUS_CMD_BUS_MAKE must not previously have been used for any other
+ control-ioctl and must be kept open for the entire life-time of the created
+ bus. Closing it will immediately cleanup the entire bus and all its associated
+ resources and endpoints. Every control file descriptor can only be used to
+ create a single new bus; from that point on, it is not used for any further
+ communication until the final close().
+ </para>
+ <para>
+ Each bus will generate a random, 128-bit UUID upon creation. This UUID will be
+ returned to creators of connections through kdbus_cmd_hello.id128 and can
+ be used by userspace to uniquely identify buses, even across different machines
+ or containers. The UUID will have its variant bits set to 'DCE', and denote
+ version 4 (random). For more details on UUIDs, see
+ <ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier">
+ the Wikipedia entry on UUIDs</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Creating buses and endpoints</title>
+ <para>
+ To create a new bus, the <varname>KDBUS_CMD_BUS_MAKE</varname>
+ command is used. It takes a <varname>struct kdbus_cmd_make</varname> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd_make {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ 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>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_MAKE_ACCESS_GROUP</varname></term>
+ <listitem>
+ <para>Make the bus or endpoint file group-accessible</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_MAKE_ACCESS_WORLD</varname></term>
+ <listitem>
+ <para>Make the bus or endpoint file world-accessible</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <varname>KDBUS_CMD_BUS_MAKE</varname>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
+ <listitem>
+ <para>Contains a string to identify the bus name.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_PARAMETER</varname></term>
+ <listitem>
+ <para>Bus-wide bloom parameters passed in a
+ <varname>struct kdbus_bloom_parameter</varname>. These
+ settings are copied back to new connections verbatim.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_RECV</varname></term>
+ <listitem>
+ <para>An optional item that contains a set of required attach
+ flags that connections must allow. This item is used as a negotiation
+ measure during connection creation. If connections do not satisfy
+ the bus requirements, they are not allowed on the bus.
+ If not set, the bus does not require any metadata to be attached;
+ in this case connections are free to set their own attach flags.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_SEND</varname></term>
+ <listitem>
+ <para>An optional item that contains a set of attach flags that are
+ returned to connections when they query the bus creator metadata.
+ If not set, no metadata is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with -EINVAL.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_BUS_MAKE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ The flags supplied in the <varname>struct kdbus_cmd_make</varname>
+ are invalid or the supplied name does not start with the current
+ UID and a '-'.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EEXIST</varname></term>
+ <listitem><para>
+ A bus of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESHUTDOWN</varname></term>
+ <listitem><para>
+ The kdbus mount instance for the bus was already shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EMFILE</varname></term>
+ <listitem><para>
+ The maximum number of buses for the current user is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member><citerefentry><refentrytitle>kdbus</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.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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.connection">
+
+ <refentryinfo>
+ <title>kdbus.connection</title>
+ <productname>kdbus.connection</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.connection</refname>
+ <refpurpose>kdbus connection</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Connections are identified by their <emphasis>connection ID</emphasis>,
+ internally implemented as a <varname>uint64_t</varname> counter.
+ The IDs of every newly created bus start at 1, and every new
+ connection will increment the counter by 1. The IDs are not reused.
+ </para>
+ <para>
+ In higher level tools, the user visible representation of a connection is
+ defined by the D-Bus protocol specification as
+ <emphasis>":1.<ID>"</emphasis>.
+ </para>
+ <para>
+ Messages with a specific <varname>uint64_t</varname> destination ID are
+ directly delivered to the connection with the corresponding ID. Messages
+ with the special destination ID <varname>KDBUS_DST_ID_BROADCAST</varname>
+ are broadcast messages and are potentially delivered to all currently
+ active connections on the bus. However, in order to receive any broadcast
+ messages, clients must subscribe to the specific messages in which they are
+ interested in.
+ </para>
+ <para>
+ Messages synthesized and sent directly by the kernel will carry the special
+ source ID <varname>KDBUS_SRC_ID_KERNEL</varname> (0).
+ </para>
+ <para>
+ In addition to the unique <varname>uint64_t</varname> connection ID,
+ established connections can request the ownership of
+ <emphasis>well-known names</emphasis>, under which they can be found and
+ addressed by other bus clients. A well-known name is associated with one
+ and only one connection at a time. See
+ <citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ on name acquisition, the name registry, and the validity of names.
+ </para>
+ <para>
+ Messages can specify the special destination ID 0 and carry a well-known name
+ in the message data. Such a message is delivered to the destination connection
+ which owns that well-known name.
+ </para>
+
+ <programlisting><![CDATA[
+ +-------------------------------------------------------------------------+
+ | +---------------+ +---------------------------+ |
+ | | Connection | | Message | -----------------+ |
+ | | :1.22 | --> | src: 22 | | |
+ | | | | dst: 25 | | |
+ | | | | | | |
+ | | | | | | |
+ | | | +---------------------------+ | |
+ | | | | |
+ | | | <--------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | -----+ | |
+ | | :1.25 | --> | src: 25 | | |
+ | | | | dst: 0xffffffffffffffff | -------------+ | |
+ | | | | (KDBUS_DST_ID_BROADCAST) | | | |
+ | | | | | ---------+ | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <--------------------------------------------------+ |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ +---------------------------+ | | |
+ | | Connection | | Message | --+ | | |
+ | | :1.55 | --> | src: 55 | | | | |
+ | | | | dst: 0 / org.foo.bar | | | | |
+ | | | | | | | | |
+ | | | | | | | | |
+ | | | +---------------------------+ | | | |
+ | | | | | | |
+ | | | <------------------------------------------+ | |
+ | +---------------+ | | |
+ | | | |
+ | +---------------+ | | |
+ | | Connection | | | |
+ | | :1.81 | | | |
+ | | org.foo.bar | | | |
+ | | | | | |
+ | | | | | |
+ | | | <-----------------------------------+ | |
+ | | | | |
+ | | | <----------------------------------------------+ |
+ | +---------------+ |
+ +-------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating connections</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file of a bus and
+ becoming an active client with the <varname>KDBUS_CMD_HELLO</varname>
+ ioctl. Every connected client connection has a unique identifier on the
+ bus and can address messages to every other connection 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.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_hello {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ __u64 attach_flags_send;
+ __u64 attach_flags_recv;
+ __u64 bus_flags;
+ __u64 id;
+ __u64 pool_size;
+ __u64 offset;
+ __u8 id128[16];
+ 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 apply to this connection</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_HELLO_ACCEPT_FD</varname></term>
+ <listitem>
+ <para>
+ When this flag is set, the connection can be sent file
+ descriptors as message payload. If it's not set, an attempt
+ to send file descriptors results in <varname>-ECOMM</varname>
+ on the sender's side.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_HELLO_ACTIVATOR</varname></term>
+ <listitem>
+ <para>
+ Make this connection an activator (see below). With this bit
+ set, an item of type <varname>KDBUS_ITEM_NAME</varname> has
+ to be attached. This item describes the well-known name this
+ connection should be an activator for.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_HELLO_POLICY_HOLDER</varname></term>
+ <listitem>
+ <para>
+ Make this connection a policy holder (see below). With this
+ bit set, an item of type <varname>KDBUS_ITEM_NAME</varname>
+ has to be attached. This item describes the well-known name
+ this connection should hold a policy for.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_HELLO_MONITOR</varname></term>
+ <listitem>
+ <para>
+ Make this connection an monitor (eavesdropping) connection.
+ See the section below more information.
+ </para>
+ <para>
+ This flag can only be set by privileged bus connections. See
+ below.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_send</varname></term>
+ <listitem><para>
+ Set the bits for metadata this connection permits to be sent to the
+ receiving peer. Only metadata items that are both allowed to be sent
+ by the sender and that are requested by the receiver will effectively
+ be attached to the message. Note, however, that the bus may
+ optionally require some of those bits to be set. If the match fails,
+ <varname>-ECONNREFUSED</varname> will be returned. In either case,
+ this field will be set to the mask of metadata items that are
+ enforced by the bus. The <varname>KDBUS_FLAGS_KERNEL</varname> bit
+ will as well be set.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>attach_flags_recv</varname></term>
+ <listitem><para>
+ Request the attachment of metadata for each message received by this
+ connection. See XXX TODO XXX for more details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>bus_flags</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ flags of the bus it connected to.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ Upon successful completion of the command, this member will contain
+ the numerical ID of the new connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>pool_size</varname></term>
+ <listitem><para>
+ The size of the communication pool, in bytes. The pool can be
+ accessed by calling
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on the file descriptor that was used to issue the
+ <varname>KDBUS_CMD_HELLO</varname> ioctl.
+ </para>
+ <para>
+ See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for further information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ The kernel will return the offset in the pool where returned details
+ will be stored. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id128</varname></term>
+ <listitem><para>
+ Upon successful completion of the ioctl, this member will contain the
+ <emphasis>128-bit UUID</emphasis> of the connected bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Variable list of items containing optional additional information.
+ The following items are currently expected/valid:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CONN_DESCRIPTION</varname></term>
+ <listitem>
+ <para>
+ Contains a string that describes this connection, so it can
+ be identified later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME</varname></term>
+ <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <listitem>
+ <para>
+ For activators and policy holders only, combinations of
+ these two items describe policy access entries. See XXX TODO XXX.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CREDS</varname></term>
+ <term><varname>KDBUS_ITEM_PIDS</varname></term>
+ <term><varname>KDBUS_ITEM_SECLABEL</varname></term>
+ <listitem>
+ <para>
+ Privileged bus users may submit these types in order to
+ create connections with faked credentials. This information
+ will be returned when peer information is queried by
+ <varname>KDBUS_CMD_CONN_INFO</varname>. See below for more
+ information on retrieving information on connections.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ At the offset returned in the <varname>offset</varname> field of
+ <varname>struct kdbus_cmd_hello</varname>, the kernel will store items
+ of the following types:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_PARAMETER</varname></term>
+ <listitem>
+ <para>
+ Bloom filter parameter as defined by the bus creator.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The offset in the pool has to be freed with the
+ <varname>KDBUS_CMD_FREE</varname> ioctl. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for further information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Privileged connections</title>
+ <para>
+ A connection is considered <emphasis>privileged</emphasis> if the user
+ it was created by is the same that created the bus, or if the creating
+ task had <varname>CAP_IPC_OWNER</varname> set when it called
+ <varname>KDBUS_CMD_HELLO</varname>.
+ </para>
+ <para>
+ Privileged connections have permission to employ certain restricted
+ functions and commands, which are explained below and in other kdbus
+ manpages.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Activator and policy holder connection</title>
+ <para>
+ An <emphasis>activator</emphasis> connection is a placeholder for a
+ <emphasis>well-known name</emphasis>. Messages sent to such a connection
+ can be used by userspace to start an implementer connection, which will
+ then get all the messages from the activator copied over. An activator
+ connection cannot be used to send any message.
+ </para>
+ <para>
+ A <emphasis>policy holder</emphasis> connection only installs a policy
+ for one or more names. These policy entries are kept active as long as
+ the connection is alive, and are removed once it terminates. Such a
+ policy connection type can be used to deploy restrictions for names that
+ are not yet active on the bus. A policy holder connection cannot be used
+ to send any message.
+ </para>
+ <para>
+ The creation of activator, policy holder or monitor (eavesdropping)
+ connections is an operation restricted to privileged users on the bus.
+ See the section below on privileged connections.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Retrieving information on a connection</title>
+ <para>
+ The <varname>KDBUS_CMD_CONN_INFO</varname> ioctl can be used to retrieve
+ credentials and properties of the initial creator of a connection. This
+ ioctl uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_info {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ __u64 id;
+ __u64 offset;
+ __u64 info_size;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <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>
+ Specifies which metadata items should be attached to the answer.
+ See
+ <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The numerical ID of the connection for which information is to be
+ retrieved. If set to a non-zero value, the
+ <varname>KDBUS_ITEM_OWNED_NAME</varname> item is ignored.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns, this field will contain the offset of the
+ connection information inside the caller's pool. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for futher information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname></varname></term>
+ <listitem><para>
+ The kernel will return the size of the returned information, so applications
+ can optionally
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ specific parts of the pool. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for futher information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <varname>KDBUS_CMD_CONN_INFO</varname>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_OWNED_NAME</varname></term>
+ <listitem>
+ <para>
+ Contains the well-known name of the connection to look up as.
+ This item is mandatory if the <varname>id</varname> field is
+ set to 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ When the ioctl returns, the following struct will be stored in the
+ caller's pool at <varname>offset</varname>. The fields in this struct
+ are described below.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The connection's flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Depending on the <varname>flags</varname> field in
+ <varname>struct kdbus_cmd_info</varname>, items of types
+ <varname>KDBUS_ITEM_OWNED_NAME</varname> and
+ <varname>KDBUS_ITEM_CONN_DESCRIPTION</varname> may follow here.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <varname>KDBUS_CMD_FREE</varname> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for futher information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Getting information about a connection's bus creator</title>
+ <para>
+ The <varname>KDBUS_CMD_BUS_CREATOR_INFO</varname> ioctl takes the same
+ struct as <varname>KDBUS_CMD_CONN_INFO</varname>, but is used to retrieve
+ information about the creator of the bus the connection is attached to.
+ The metadata returned by this call is collected during the creation of
+ the bus and is never altered afterwards, so it provides pristine
+ information on the task that created the bus, at the moment when it
+ did so.
+ </para>
+ <para>
+ In response to this call, a slice in the connection's pool is allocated and
+ filled with an object of type <varname>struct kdbus_info</varname>,
+ pointed to by the ioctl's <varname>offset</varname> field.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 flags;
+ __u64 kernel_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>size</varname></term>
+ <listitem><para>
+ The overall size of the struct, including its items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>id</varname></term>
+ <listitem><para>
+ The bus ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The bus flags as specified when it was created.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Metadata information is stored in items here. The item list
+ contains a <varname>KDBUS_ITEM_MAKE_NAME</varname> item that
+ indicates the bus name of the calling connection.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Once the caller is finished with parsing the return buffer, it needs to
+ employ the <varname>KDBUS_CMD_FREE</varname> command for the offset, in
+ order to free the buffer part. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for futher information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating connection details</title>
+ <para>
+ Some of a connection's details can be updated with the
+ <varname>KDBUS_CMD_CONN_UPDATE</varname> ioctl, using the file
+ descriptor that was used to create the connection. The update command
+ uses the following struct.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_update {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ struct kdbus_item items[0];
+};
+ </programlisting>
+
+ <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>
+ Currently, no flags are supported. Reserved for future use.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to describe the connection details to be updated. The
+ following item types are supported.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_SEND</varname></term>
+ <listitem>
+ <para>
+ Supply a new set of items that this connection permits to be
+ sent along with messages.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_RECV</varname></term>
+ <listitem>
+ <para>
+ Supply a new set of items to be attached to each message.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME</varname></term>
+ <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <listitem>
+ <para>
+ Policy holder connections may supply a new set of policy
+ information with these items. For other connection types,
+ <varname>-EOPNOTSUPP</varname> is returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Monitor connections ('eavesdropper')</title>
+ <para>
+ Eavesdropping connections are created by setting the
+ <varname>KDBUS_HELLO_MONITOR</varname> flag in
+ <varname>struct kdbus_hello.flags</varname>.
+ Such connections have all properties of any other, regular connection,
+ except for the following details:
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem><para>
+ They will get every message sent over the bus, both unicasts and
+ broadcasts.
+ </para></listitem>
+
+ <listitem><para>
+ Installing matches for signal messages is neither necessary
+ nor allowed.
+ </para></listitem>
+
+ <listitem><para>
+ They cannot send messages or be directly addressed as receiver
+ </para></listitem>
+
+ <listitem><para>
+ Their creation and destruction will not cause
+ <varname>KDBUS_ITEM_ID_{ADD,REMOVE}</varname> notifications to be
+ generated, so other connections cannot detect the presence of an
+ eavesdropper.
+ </para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Termination of connections</title>
+ <para>
+ A connection can be terminated by simply calling
+ <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on its file descriptor. All pending incoming messages will be discarded,
+ and the memory allocated by the pool will be freed.
+ </para>
+
+ <para>
+ An alternative way of closing down a connection is via the
+ <varname>KDBUS_CMD_BYEBYE</varname> ioctl. This ioctl will succeed only
+ if the message queue of the connection is empty at the time of closing;
+ otherwise, <varname>-EBUSY</varname> is returned. When this ioctl returns
+ successfully, the connection has been terminated and won't accept any new
+ messages from remote peers. This way, a connection can be terminated
+ race-free, without losing any messages.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all metioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_HELLO</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EFAULT</varname></term>
+ <listitem><para>
+ The supplied pool size was 0 or not a multiple of the page size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ The flags supplied in <varname>struct kdbus_cmd_make</varname> are
+ invalid, or an illegal combination of
+ <varname>KDBUS_HELLO_MONITOR</varname>,
+ <varname>KDBUS_HELLO_ACTIVATOR</varname> and
+ <varname>KDBUS_HELLO_POLICY_HOLDER</varname> was passed in the flags,
+ or an invalid set of items was supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ECONNREFUSED</varname></term>
+ <listitem><para>
+ The attach_flags_send field did not satisfy the requirements of
+ the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EPERM</varname></term>
+ <listitem><para>
+ A <varname>KDBUS_ITEM_CREDS</varname> items was supplied, but the
+ current user is not privileged.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESHUTDOWN</varname></term>
+ <listitem><para>
+ The bus you were trying to connect to has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EMFILE</varname></term>
+ <listitem><para>
+ The maximum number of connections on the bus has been reached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EOPNOTSUPP</varname></term>
+ <listitem><para>
+ The endpoint does not support the connection flags supplied in
+ <varname>struct kdbus_cmd_hello</varname>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_BYEBYE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EALREADY</varname></term>
+ <listitem><para>
+ The connection has already been shut down.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EBUSY</varname></term>
+ <listitem><para>
+ There are still messages queued up in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_CONN_INFO</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Invalid flags, or neither an ID nor a name was provided, or the
+ name is invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESRCH</varname></term>
+ <listitem><para>
+ Connection lookup by name failed.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ENXIO</varname></term>
+ <listitem><para>
+ No connection with the provided connection ID found.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_CONN_UPDATE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Illegal flags or items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Wildcards submitted in policy entries, or illegal sequence
+ of policy items.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EOPNOTSUPP</varname></term>
+ <listitem><para>
+ Operation not supported by connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-E2BIG</varname></term>
+ <listitem><para>
+ Too many policy items attached.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </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.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.items</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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.endpoint">
+
+ <refentryinfo>
+ <title>kdbus.endpoint</title>
+ <productname>kdbus.endpoint</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.endpoint</refname>
+ <refpurpose>kdbus endpoint</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ Endpoints are entry points to a bus (see
+ <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ By default, each bus has a default
+ endpoint called 'bus'. The bus owner has the ability to create custom
+ endpoints with specific names, permissions, and policy databases (see below).
+ An endpoint is presented as file underneath the directory of the parent bus.
+ </para>
+ <para>
+ To create a custom endpoint, open the default endpoint ('bus') and use the
+ KDBUS_CMD_ENDPOINT_MAKE ioctl with "struct kdbus_cmd_make". Custom endpoints
+ always have a policy database that, by default, forbids any operation. You have
+ to explicitly install policy entries to allow any operation on this endpoint.
+ </para>
+ <para>
+ Once KDBUS_CMD_ENDPOINT_MAKE succeeded, the new endpoint will appear in the
+ filesystem
+ (<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+ and the used file descriptor will manage the
+ newly created endpoint resource. It cannot be used to manage further resources
+ and must be kept open as long as the endpoint is needed. The endpoint will be
+ terminated as soon as the file descriptor is closed.
+ </para>
+ <para>
+ Endpoint names may be chosen freely except for one restriction: the name must
+ be prefixed with the numeric effective UID of the creator and a dash. This is
+ required to avoid namespace clashes between different users. When creating an
+ endpoint, the name that is passed in must be properly formatted or the kernel
+ will refuse creation of the endpoint. Example: "1047-foobar" is an acceptable
+ name for an endpoint registered by a user with UID 1047. However,
+ "1024-my-endpoint" is not, and neither is "my-endpoint". The UID must be
+ provided in the user-namespace of the parent domain.
+ </para>
+ <para>
+ To create connections to a bus, use KDBUS_CMD_HELLO on a file descriptor returned by
+ <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on an endpoint node.
+ See <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for further details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Creating custom endpoints</title>
+ <para>
+ To create a new endpoint, the <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>
+ command is used. It takes a <varname>struct kdbus_cmd_make</varname> argument.
+ </para>
+ <programlisting>
+struct kdbus_cmd_make {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ 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>The flags for creation.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_MAKE_ACCESS_GROUP</varname></term>
+ <listitem>
+ <para>Make the endpoint file group-accessible</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_MAKE_ACCESS_WORLD</varname></term>
+ <listitem>
+ <para>Make the endpoint file world-accessible</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are expected for
+ <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
+ <listitem>
+ <para>Contains a string to identify the endpoint name.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Updating endpoints</title>
+ <para>
+ TODO!! Document KDBUS_CMD_ENPOINT_UPDATE
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all mentioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ The flags supplied in the <varname>struct kdbus_cmd_make</varname>
+ are invalid.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EEXIST</varname></term>
+ <listitem><para>
+ An endpoint of that name already exists.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EPERM</varname></term>
+ <listitem><para>
+ The calling user is not privileged. See
+ <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for information about privileged users.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </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.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.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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_fs">
+
+ <refentryinfo>
+ <title>kdbus.fs</title>
+ <productname>kdbus.fs</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.fs</refname>
+ <refpurpose>kdbus file system</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>File-system Layout</title>
+
+ <para>The <emphasis>kdbusfs</emphasis>
+ pseudo file-system provides access to internal kdbus entities,
+ including buses and endpoints. Each time you mount it, a new
+ instance (called <emphasis>domain</emphasis>) will be created
+ which is independent of the other domains.</para>
+
+ <para>Following, you can see an example layout of the
+ <emphasis>kdbusfs</emphasis> file-system:</para>
+
+<programlisting>
+ /sys/fs/kdbus/ ; mount-point
+ |-- 0-system ; bus directory
+ | |-- bus ; default endpoint
+ | `-- 1017-custom ; custom endpoint
+ |-- 1000-user ; bus directory
+ | |-- bus ; default endpoint
+ | |-- 1000-service-A ; custom endpoint
+ | `-- 1000-service-B ; custom endpoint
+ `-- control ; control file
+</programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Mounting instances</title>
+ <para>In order to get a new and separate kdbus environment, new instance
+ of <emphasis>kdbusfs</emphasis> can be mounted like this:
+<programlisting>
+ # mount -t kdbusfs kdbusfs /tmp/new_kdbus/
+</programlisting>
+ </para>
+
+ <para>Busses created in this new instance will be entirely separated and
+ not influence any other kdbus instances on the system.</para>
+ </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.item</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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">
+
+ <refentryinfo>
+ <title>kdbus.item</title>
+ <productname>kdbus item</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@gmail.com</email>
+ </author>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Daniel</firstname>
+ <surname>Mack</surname>
+ <email>kdbus@zonque.org</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.item</refname>
+ <refpurpose>Kernel item structure</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ To flexibly augment transport structures, data blobs of type
+ <varname>struct kdbus_item</varname>
+ can be attached to the structs passed into the ioctls. Some ioctls make items
+ of certain types mandatory, others are optional. Items that are unsupported
+ by ioctls they are sent to will cause the ioctl to fail
+ <varname>-EINVAL.</varname>
+ Items are also used for information stored in a connection's
+ <emphasis>pool</emphasis>, such as received messages, name lists or
+ requested connection or bus owner information. Depending on the type of
+ an item, its total size is either fixed or variable.
+ The kernel expects all items to be aligned to 8-byte boundaries. Unaligned
+ items or items that are unsupported by the ioctl are rejected.
+ </para>
+
+ <para>Whenever items are used as part of the kdbus kernel API, they are embedded in
+ structs that are embedded inside structs that themselves include a size field
+ containing the overall size of the structure. This allows multiple items to
+ be chained up.
+ </para>
+
+ <refsect2>
+ <title>Iterating items</title>
+ <para>A simple iterator in userspace would iterate over the items until the items
+ have reached the embedding structure's overall size. An example implementation
+ is shown below.
+ </para>
+
+ <programlisting><![CDATA[
+#define KDBUS_ALIGN8(l) (((l) + 7) & ~7)
+
+#define KDBUS_ITEM_NEXT(item) \
+ (typeof(item))(((uint8_t *)item) + KDBUS_ALIGN8((item)->size))
+
+#define KDBUS_ITEM_FOREACH(item, head, first) \
+ for (item = (head)->first; \
+ ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \
+ ((uint8_t *)(item) >= (uint8_u *)(head)); \
+ item = KDBUS_ITEM_NEXT(item))
+ ]]></programlisting>
+ </refsect2>
+
+ <refsect2>
+ <title>Item layout</title>
+ <para>A <varname>struct kdbus_item</varname> consists of a
+ <varname>size</varname> field, describing its overall size,
+ and a <varname>type</varname> field, both 64 bit wide. They are followed by
+ a union to store information that is specific to the item's type.
+ A shortened version is shown below.
+ </para>
+
+ <programlisting>
+struct kdbus_item {
+ __u64 size;
+ __u64 type;
+ union {
+ /* item type specific payload - see below */
+ };
+};
+ </programlisting>
+
+ <para><varname>struct kdbus_item</varname> should never be
+ used to allocate an item instance, as its size may grow in future
+ releases of the API. Instead, it should be manually assembled by storing
+ the <varname>size</varname>, <varname>type</varname>
+ and payload to a struct of its own.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Item types</title>
+
+ <para>Items exchanged between userspace and kernel</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_PAYLOAD_VEC</varname></term>
+ <listitem><para>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_PAYLOAD_OFF</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_PAYLOAD_MEMFD</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_FDS</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CANCEL_FD</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_PARAMETER</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_FILTER</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_MASK</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_DST_NAME</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_SEND</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ATTACH_FLAGS_RECV</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ID</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Items attached by the kernel as metadata</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_TIMESTAMP</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CREDS</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_PIDS</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_AUXGROUPS</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_OWNED_NAME</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_TID_COMM</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_PID_COMM</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_EXE</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CMDLINE</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CGROUP</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CAPS</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_SECLABEL</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_AUDIT</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CONN_DESCRIPTION</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Items used for policy entries, matches and notifications</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME_ADD</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME_REMOVE</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_NAME_CHANGE</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ID_ADD</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_ID_REMOVE</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_REPLY_TIMEOUT</varname></term>
+ <listitem><para>TODO
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_REPLY_DEAD</varname></term>
+ <listitem><para>TODO
+ </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.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?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>
+ Messages are passed to the kernel with the <varname>KDBUS_CMD_SEND</varname>
+ ioctl. Depending on the destination address of the message, the kernel
+ delivers the message to the specific destination connection, or to 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 below).
+ </para>
+
+ <para>
+ The <varname>KDBUS_CMD_SEND</varname> ioctl uses a
+ <varname>struct kdbus_cmd_send</varname> to describe the message
+ transfer.
+ </para>
+ <programlisting>
+struct kdbus_cmd_send {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 kernel_msg_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><varname>KDBUS_SEND_SYNC_REPLY</varname></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 KDBUS_MSG_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.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>msg_address</varname></term>
+ <listitem><para>
+ In this field, userspace has to provide a pointer to a message
+ (<varname>struct kdbus_msg</varname>) 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
+ <varname>struct kdbus_cmd_recv</varname> for more details.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ The following items are currently recognized.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_CANCEL_FD</varname></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 poll() on this file descriptor,
+ and if it reports any incoming bytes, the blocking send operation will
+ be canceled, and the call will return -ECANCELED. Any type of file
+ descriptor that implements poll() can be used as payload to this item.
+ For asynchronous message sending, this item is accepted but ignored.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All other items are rejected, and the ioctl will fail with -EINVAL.
+ </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><varname>KDBUS_MSG_EXPECT_REPLY</varname></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 <varname>CLOCK_MONOTONIC</varname>.
+ </para><para>
+ For a message to be accepted as reply, it must be a direct message to
+ the original sender (not a broadcast), and its kdbus_msg.reply_cookie
+ must match the previous message's kdbus_msg.cookie.
+ </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><varname>KDBUS_MSG_NO_AUTO_START</varname></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,
+ <varname>-EADDRNOTAVAIL</varname> is returned from the ioctl.
+ </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 zero.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dst_id</varname></term>
+ <listitem><para>
+ The numeric ID of the destination connection, or
+ <varname>KDBUS_DST_ID_BROADCAST</varname>
+ (~0ULL) to address every peer on the bus, or
+ <varname>KDBUS_DST_ID_NAME</varname> (0) to look
+ it up dynamically from the bus' name registry.
+ In the latter case, an item of type
+ <varname>KDBUS_ITEM_DST_NAME</varname> is mandatory.
+ </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
+ <varname>KDBUS_PAYLOAD_DBUS</varname> is accepted as input value
+ of this field. When receiving messages that are generated by the
+ kernel (notifications), this field will contain
+ <varname>KDBUS_PAYLOAD_KERNEL</varname>.
+ </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
+ <varname>CLOCK_MONOTONIC</varname>. 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><varname>KDBUS_ITEM_PAYLOAD_VEC</varname></term>
+ <term><varname>KDBUS_ITEM_PAYLOAD_MEMFD</varname></term>
+ <term><varname>KDBUS_ITEM_FDS</varname></term>
+ <listitem>
+ <para>
+ Actual data records containing the payload. See section
+ "Passing of Payload Data".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_BLOOM_FILTER</varname></term>
+ <listitem>
+ <para>
+ Bloom filter for matches (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ITEM_DST_NAME</varname></term>
+ <listitem>
+ <para>
+ Well-known name to send this message to. Required if
+ <varname>dst_id</varname> is set to
+ <varname>KDBUS_DST_ID_NAME</varname>.
+ If a connection holding the given name can't be found,
+ <varname>-ESRCH</varname> 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 userspace 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 TODO!
+ </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>Passing of Payload Data</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 mmap()ed by
+ the receiver.
+ </para>
+ <para>
+ See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ The following items are used to carry the actual data payload of a message.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_MSG_PAYLOAD_VEC</varname></term>
+ <listitem>
+ <para>
+ Messages are directly copied by the sending process 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.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_MSG_PAYLOAD_MEMFD</varname></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
+ <varname>(F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL)</varname>
+ 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.
+ </para>
+ <para>
+ Apart from the sender filling-in the content into memfd files, the data will
+ be passed as zero-copy from one process to another, read-only, shared between
+ the peers.
+ </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 VEC and MEMFD
+ payloads. For instance, the kernel may decide to merge multiple VECs into a
+ single VEC, inline MEMFD payloads into memory or merge all passed VECs into a
+ single MEMFD. However, the kernel preserves the order of passed data. This
+ means that the order of all VEC and MEMFD items is not changed in respect to
+ each other.
+ </para>
+ <para>
+ In other words: All passed VEC and MEMFD data payloads are treated as a single
+ stream of data that may be received by the remote peer in a different set of
+ hunks than it was sent as.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <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.
+ </para>
+
+ <para>
+ With the KDBUS_CMD_RECV ioctl, a <varname>struct kdbus_cmd_recv</varname> is used.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_recv {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_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><varname>KDBUS_RECV_PEEK</varname></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><varname>KDBUS_RECV_DROP</varname></term>
+ <listitem>
+ <para>
+ Drop the next message without doing anything else with it,
+ and free the pool slice. This a short-cut for
+ <varname>KDBUS_RECV_PEEK</varname> and
+ <varname>KDBUS_CMD_FREE</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_RECV_USE_PRIORITY</varname></term>
+ <listitem>
+ <para>
+ Dequeue the messages ordered by their priority, and filtering
+ them with the priority field (see below).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>priority</varname></term>
+ <listitem><para>
+ With <varname>KDBUS_RECV_USE_PRIORITY</varname> 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, <varname>-ENOMSG</varname> is returned.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>dropped_msgs</varname></term>
+ <listitem><para>
+ If the <varname>CMD_RECV</varname> ioctl fails with
+ <varname>-EOVERFLOW</varname>, this field is filled by
+ the kernel with the number of messages that couldn't be transmitted
+ to this receiving connection. In that case, the
+ <varname>offset</varname> member must not be accessed.
+ </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>-EINVAL</varname>,
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Both <varname>struct kdbus_cmd_recv</varname> and
+ <varname>struct kdbus_cmd_send</varname> embed
+ <varname>struct kdbus_msg_info</varname>.
+ For the <varname>KDBUS_CMD_SEND</varname> 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
+ <varname>KDBUS_CMD_FREE</varname>. 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
+ <varname>struct kdbus_msg</varname> 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><varname>KDBUS_RECV_RETURN_INCOMPLETE_FDS</varname></term>
+ <listitem>
+ <para>
+ The message contained file descriptors which couldn't be installed
+ into the receiver's task. Most probably that happened because the
+ maximum number of file descriptors for that task were exceeded.
+ The message is still delivered, so this is not a fatal condition.
+ File descriptors inside the <varname>KDBUS_ITEM_FDS</varname>
+ item that could not be installed will be set to -1.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Unless <varname>KDBUS_RECV_DROP</varname> was passed after a successful+
+ <varname>KDBUS_CMD_RECV</varname> ioctl, the <varname>offset</varname>
+ field contains the location of the new message inside the receiver's
+ pool. The message is stored as <varname>struct kdbus_msg</varname> 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
+ (<varname>KDBUS_HELLO_ACCEPT_FD</varname>), and if the message contained
+ any, they will be installed into the receiving process when the
+ <varname>KDBUS_CMD_RECV</varname> ioctl is called.
+ The receiving task is obliged to close all of them appropriately. If
+ <varname>KDBUS_RECV_PEEK</varname> is set, no file descriptors are
+ installed. This allows for peeking at a message and dropping it via
+ <varname>KDBUS_RECV_DROP</varname>, without installing the passed file
+ descriptors into the receiving process.
+ </para>
+ <para>
+ The caller is obliged to call the <varname>KDBUS_CMD_FREE</varname>
+ 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 mark='opencircle'>
+ <listitem><para>kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL</para></listitem>
+ <listitem><para>kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST</para></listitem>
+ <listitem><para>kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL</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.
+ </para>
+
+ <para>
+ The kernel will notify its users of the following events.
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem><para>
+ When connection A is terminated while connection B is waiting for a
+ reply from it, connection B is notified with a message with an item of
+ type <varname>KDBUS_ITEM_REPLY_DEAD</varname>.
+ </para></listitem>
+
+ <listitem><para>
+ When connection A does not receive a reply from connection B within the
+ specified timeout window, connection A will receive a message with an
+ item of type <varname>KDBUS_ITEM_REPLY_TIMEOUT</varname>.
+ </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
+ <varname>KDBUS_ITEM_ID_ADD</varname> or
+ <varname>KDBUS_ITEM_ID_REMOVE</varname>, 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 <varname>KDBUS_ITEM_NAME_ADD</varname>,
+ <varname>KDBUS_ITEM_NAME_REMOVE</varname> or
+ <varname>KDBUS_ITEM_NAME_CHANGE</varname> 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 metioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_SEND</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EOPNOTSUPP</varname></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><varname>-EINVAL</varname></term>
+ <listitem><para>
+ The submitted payload type is <varname>KDBUS_PAYLOAD_KERNEL</varname>,
+ <varname>KDBUS_MSG_EXPECT_REPLY</varname> was set without timeout or
+ cookie values, <varname>KDBUS_SEND_SYNC_REPLY</varname> was set
+ without <varname>KDBUS_MSG_EXPECT_REPLY</varname>, an invalid item
+ was supplied, <varname>src_id</varname> 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><varname>-ENOTUNIQ</varname></term>
+ <listitem><para>
+ The supplied destination is <varname>KDBUS_DST_ID_BROADCAST</varname>,
+ a file descriptor was passed, <varname>KDBUS_MSG_EXPECT_REPLY</varname>
+ was set, or a timeout was given for a broadcast message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-E2BIG</varname></term>
+ <listitem><para>
+ Too many items
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EMSGSIZE</varname></term>
+ <listitem><para>
+ The size of the message header and items or the payload vector
+ is excessive.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EEXIST</varname></term>
+ <listitem><para>
+ Multiple <varname>KDBUS_ITEM_FDS</varname>,
+ <varname>KDBUS_ITEM_BLOOM_FILTER</varname> or
+ <varname>KDBUS_ITEM_DST_NAME</varname> items were supplied.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EBADF</varname></term>
+ <listitem><para>
+ The supplied <varname>KDBUS_ITEM_FDS</varname> or
+ <varname>KDBUS_ITEM_PAYLOAD_MEMFD</varname> items
+ contained an illegal file descriptor.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EMEDIUMTYPE</varname></term>
+ <listitem><para>
+ The supplied memfd is not a sealed kdbus memfd.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EMFILE</varname></term>
+ <listitem><para>
+ Too many file descriptors inside a <varname>KDBUS_ITEM_FDS</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EBADMSG</varname></term>
+ <listitem><para>
+ An item had illegal size, both a <varname>dst_id</varname> and a
+ <varname>KDBUS_ITEM_DST_NAME</varname> was given, or both a name
+ and a bloom filter was given.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ETXTBSY</varname></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><varname>-ECOMM</varname></term>
+ <listitem><para>
+ A peer does not accept the file descriptors addressed to it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EFAULT</varname></term>
+ <listitem><para>
+ The supplied bloom filter size was not 64-bit aligned or memory
+ supplied by userspace could not be accessed by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EDOM</varname></term>
+ <listitem><para>
+ The supplied bloom filter size did not match the bloom filter
+ size of the bus.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EDESTADDRREQ</varname></term>
+ <listitem><para>
+ <varname>dst_id</varname> was set to
+ <varname>KDBUS_DST_ID_NAME</varname>, but no
+ <varname>KDBUS_ITEM_DST_NAME</varname> was attached.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESRCH</varname></term>
+ <listitem><para>
+ The name to look up was not found in the name registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EADDRNOTAVAIL</varname></term>
+ <listitem><para>
+ <varname>KDBUS_MSG_NO_AUTO_START</varname> was given but the
+ destination connection is an activator.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ENXIO</varname></term>
+ <listitem><para>
+ The passed numeric destination connection ID couldn't be found,
+ or is not connected.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ECONNRESET</varname></term>
+ <listitem><para>
+ The destination connection is no longer active.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ETIMEDOUT</varname></term>
+ <listitem><para>
+ Timeout while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINTR</varname></term>
+ <listitem><para>
+ Interrupted system call while synchronously waiting for a reply.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EPIPE</varname></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><varname>-ENOBUFS</varname></term>
+ <listitem><para>
+ Too many pending messages on the receiver side.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EREMCHG</varname></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><varname>-EXFULL</varname></term>
+ <listitem><para>
+ The memory pool of the receiver is full.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EREMOTEIO</varname></term>
+ <listitem><para>
+ While synchronously waiting for a reply, the remote peer
+ failed with an I/O error.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_RECV</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EOPNOTSUPP</varname></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><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Invalid flags or offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EAGAIN</varname></term>
+ <listitem><para>
+ No message found in the queue
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ENOMSG</varname></term>
+ <listitem><para>
+ No message of the requested priority found.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EOVERFLOW</varname></term>
+ <listitem><para>
+ Some messages have been lost.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </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.items</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</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>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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.names">
+
+ <refentryinfo>
+ <title>kdbus.names</title>
+ <productname>kdbus.names</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.names</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.names</refname>
+ <refpurpose>kdbus names</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Each
+ <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ instantiates a name registry to resolve well-known names into unique
+ connection IDs for message delivery. The registry will be queried when a
+ message is sent with <varname>kdbus_msg.dst_id</varname> set to
+ <varname>KDBUS_DST_ID_NAME</varname>, or when a registry dump is
+ requested.
+ </para>
+
+ <para>
+ All of the below is subject to policy rules for SEE and OWN permissions.
+ See
+ <citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Name validity</title>
+ <para>
+ A name has to comply with the following rules to be considered valid.
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem><para>
+ The name has two or more elements separated by a period ('.') character
+ </para></listitem>
+ <listitem><para>
+ All elements must contain at least one character
+ </para></listitem>
+ <listitem><para>
+ Each element must only contain the ASCII characters "[A-Z][a-z][0-9]_"
+ and must not begin with a digit
+ </para></listitem>
+ <listitem><para>
+ The name must contain at least one '.' (period) character
+ (and thus at least two elements)
+ </para></listitem>
+ <listitem><para>
+ The name must not begin with a '.' (period) character
+ </para></listitem>
+ <listitem><para>
+ The name must not exceed KDBUS_NAME_MAX_LEN (255)
+ </para></listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Acquiring a name</title>
+ <para>
+ To acquire a name, a client uses the
+ <varname>KDBUS_CMD_NAME_ACQUIRE</varname> ioctl with the following data
+ structure.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_name {
+ __u64 size;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ 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 details in the name acquisition.</para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_NAME_REPLACE_EXISTING</varname></term>
+ <listitem>
+ <para>
+ Acquiring a name that is already present usually fails,
+ unless this flag is set in the call, and
+ <varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname> (see below)
+ was set when the current owner of the name acquired it, or
+ if the current owner is an activator connection (see
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname></term>
+ <listitem>
+ <para>
+ Allow other connections to take over this name. When this
+ happens, the former owner of the connection will be notified
+ of the name loss.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_QUEUE</varname></term>
+ <listitem>
+ <para>
+ A name that is already acquired by a connection, and which
+ wasn't requested with the
+ <varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname> flag set can
+ not be acquired again. However, a connection can put itself
+ in a queue of connections waiting for the name to be released.
+ Once that happens, the first connection in that queue becomes
+ the new owner and is notified accordingly.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <varname>KDBUS_ITEM_NAME</varname> is expected and allowed, and
+ the contained string must be a valid bus name.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Releasing a name</title>
+ <para>
+ A connection may release a name explicitly with the
+ <varname>KDBUS_CMD_NAME_RELEASE</varname> ioctl. If the connection was
+ an implementer of an activatable name, its pending messages are moved
+ back to the activator. If there are any connections queued up as waiters
+ for the name, the first one in the queue (the oldest entry) will become
+ the new owner. The same happens implicitly for all names once a
+ connection terminates. See
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more information on connections.
+ </para>
+ <para>
+ The <varname>KDBUS_CMD_NAME_RELEASE</varname> ioctl uses the same data
+ structure as the acquisition call (<varname>KDBUS_CMD_NAME_ACQUIRE</varname>),
+ but with slightly different field usage.
+ </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.
+ See section 3.2 for more details.
+
+ __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>
+
+ <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 the command. Currently unused and must be zero.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <varname>KDBUS_ITEM_NAME</varname> is expected and allowed, and
+ the contained string must be a valid bus name.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>-EINVAL</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Dumping the name registry</title>
+ <para>
+ A connection may request a complete or filtered dump of currently active
+ bus names with the <varname>KDBUS_CMD_NAME_LIST</varname> ioctl, which
+ takes a <varname>struct kdbus_cmd_name_list</varname> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_name_list {
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ __u64 offset;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>
+ Any combination of flags to specify which names should be dumped.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_NAME_LIST_UNIQUE</varname></term>
+ <listitem>
+ <para>
+ List the unique (numeric) IDs of the connection, whether it
+ owns a name or not.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_LIST_NAMES</varname></term>
+ <listitem>
+ <para>
+ List well-known names stored in the database which are
+ actively owned by a real connection (not an activator).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_LIST_ACTIVATORS</varname></term>
+ <listitem>
+ <para>
+ List names that are owned by an activator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_LIST_QUEUED</varname></term>
+ <listitem>
+ <para>
+ List connections that are not yet owning a name but are
+ waiting for it to become available.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns successfully, the offset to the name registry
+ dump inside the connection's pool will be stored in this field.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned list of names is stored in a
+ <varname>struct kdbus_name_list</varname> that in turn
+ contains a dynamic number of
+ <varname>struct kdbus_cmd_name</varname> that carry the actual
+ information. The fields inside that
+ <varname>struct kdbus_cmd_name</varname> is described next.
+ </para>
+
+ <programlisting>
+struct kdbus_name_info {
+ __u64 size;
+ __u64 owner_id;
+ __u64 conn_flags;
+ 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>owner_id</varname></term>
+ <listitem><para>
+ The owning connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>conn_flags</varname></term>
+ <listitem><para>
+ The flags of the owning connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>
+ Items containing the actual name. Currently, one item of type
+ <varname>KDBUS_ITEM_OWNED_NAME</varname> will be attached,
+ including the name's flags. In that item, the flags field of the
+ name may carry the following bits:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname></term>
+ <listitem>
+ <para>
+ Other connections are allowed to take over this name from the
+ connection that owns it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_IN_QUEUE</varname></term>
+ <listitem>
+ <para>
+ When retrieving a list of currently acquired names in the
+ registry, this flag indicates whether the connection
+ actually owns the name or is currently waiting for it to
+ become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_NAME_ACTIVATOR</varname></term>
+ <listitem>
+ <para>
+ An activator connection owns a name as a placeholder for an
+ implementer, which is started on demand by userspace as soon
+ as the first message arrives. There's some more information
+ on this topic in
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ .
+ </para>
+ <para>
+ In contrast to <varname>KDBUS_NAME_REPLACE_EXISTING</varname>,
+ when a name is taken over from an activator connection, all
+ the messages that have been queued in the activator
+ connection will be moved over to the new owner. The activator
+ connection will still be tracked for the name and will take
+ control again if the implementer connection terminates.
+ </para>
+ <para>
+ This flag can not be used when acquiring a name, but is implicitly set
+ through <varname>KDBUS_CMD_HELLO</varname> with
+ <varname>KDBUS_HELLO_ACTIVATOR</varname> set in
+ <varname>kdbus_cmd_hello.conn_flags</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned buffer must be freed with the KDBUS_CMD_FREE ioctl when the user
+ is finished with it. See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all metioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_NAME_ACQUIRE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Illegal command flags, illegal name provided, or an activator
+ tried to acquire a second name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EPERM</varname></term>
+ <listitem><para>
+ Policy prohibited name ownership.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EALREADY</varname></term>
+ <listitem><para>
+ Connection already owns that name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EEXIST</varname></term>
+ <listitem><para>
+ The name already exists and can not be taken over.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-E2BIG</varname></term>
+ <listitem><para>
+ The maximum number of well-known names per connection is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_NAME_RELEASE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Invalid command flags, or invalid name provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESRCH</varname></term>
+ <listitem><para>
+ Name is not found in the registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EADDRINUSE</varname></term>
+ <listitem><para>
+ Name is owned by a different connection and can't be released.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ <varname>KDBUS_CMD_NAME_LIST</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Invalid command flags
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ENOBUFS</varname></term>
+ <listitem><para>
+ No available memory in the connection's pool.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </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.items</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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.pool">
+
+ <refentryinfo>
+ <title>kdbus.pool</title>
+ <productname>kdbus.pool</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.pool</refname>
+ <refpurpose>kdbus pool</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ A pool for data received from the kernel is installed for every
+ <emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and
+ is sized according to the information stored in the
+ <varname>KDBUS_ITEM_BLOOM_PARAMETER</varname> item that is returned by
+ <varname>KDBUS_CMD_HELLO</varname>.
+ </para>
+
+ <para>
+ The pool is written to by the kernel when one of the following
+ <emphasis>ioctls</emphasis> is issued:
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_CMD_HELLO</varname></term>
+ <listitem><para>
+ ... to receive details about the bus the connection was made to
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>KDBUS_CMD_RECV</varname></term>
+ <listitem><para>
+ ... to receive a message
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>KDBUS_CMD_NAME_LIST</varname></term>
+ <listitem><para>
+ ... to dump the name registry
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>KDBUS_CMD_CONN_INFO</varname></term>
+ <listitem><para>
+ ... to retrieve information on a connection
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </para>
+ <para>
+ The offsets returned by either one of the aforementioned ioctls describe offsets
+ inside the pool. In order to make the slice available for subsequent calls,
+ KDBUS_CMD_FREE has to be called on the offset (see below).
+
+ To access the memory, the caller is expected to
+ <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ it, like this:
+ </para>
+ <programlisting>
+/*
+ * POOL_SIZE has to be a multiple of PAGE_SIZE, and it must match the
+ * value that was previously returned through the KDBUS_ITEM_BLOOM_PARAMETER
+ * item field when the KDBUS_CMD_HELLO ioctl returned.
+ */
+
+buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0);
+ </programlisting>
+
+ <para>
+ Alternatively, instead of mapping the entire pool buffer, only parts of it can
+ be mapped. The length of the response is returned by the kernel along with the
+ offset for each of the ioctls listed above.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ TODO: some words about how slices are alllocated ...
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Freeing pool slices</title>
+ <para>
+ The <varname>KDBUS_CMD_FREE</varname> ioctl is used to free a slice
+ inside the pool, described an offset that was returned in an 'offset'
+ field of another ioctl struct. The command takes a
+ <varname>struct kdbus_cmd_free</varname> as argument:
+ </para>
+
+<programlisting>
+struct kdbus_cmd_free {
+ __u64 size;
+ __u64 offset;
+ __u64 flags;
+ __u64 kernel_flags;
+ __u64 return_flags;
+ 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>offset</varname></term>
+ <listitem><para>
+ The offset to free, as returned by other ioctls that allocated
+ memory for returned information.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>kernel_flags</varname></term>
+ <listitem><para>
+ Valid flags for this command, returned by the kernel upon each call.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>return_flags</varname></term>
+ <listitem><para>
+ Flags returned by the kernel. Currently unused and always set to
+ zero by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem><para>
+ Items to specify further details for the receive command.
+ Currently unused. All items will be rejected with -EINVAL.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Return value</title>
+ <para>
+ On success, all metioned ioctl commands return 0.
+ </para>
+
+ <para>
+ <varname>KDBUS_CMD_FREE</varname> may return the following errors.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-ENXIO</varname></term>
+ <listitem><para>
+ No pool slice found at given offset.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ Invalid flags provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+ <listitem><para>
+ The offset is valid, but the user is not allowed to free the slice.
+ This happens, for example, if the offset was retrieved with
+ <varname>KDBUS_RECV_PEEK</varname>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </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.items</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ </simplelist>
+ </refsect1>
+</refentry>
--- /dev/null
+<?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">
+
+ <refentryinfo>
+ <title>kdbus</title>
+ <productname>kdbus</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@gmail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus</refname>
+ <refpurpose>Kernel Message Bus</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ kdbus is an inter-process communication bus system
+ controlled by the kernel. It provides user-space with a bus API
+ to send unicast and multicast messages to one, or many, peers
+ connected to the same bus.
+ It does not enforce any layout on the transmitted data, but
+ only provides the transport layer used for message interchange
+ between peers.
+ </para>
+
+ <para>
+ kdbus provides a pseudo file-system called
+ <emphasis>kdbusfs</emphasis>, which is usually mounted on
+ <filename>/sys/fs/kdbus</filename>. Buses and their endpoints
+ can be accessed as sub-directories and files underneath this
+ mount-point. Any advanced operations are done via
+ <function>ioctl()</function> on files created by
+ <emphasis>kdbusfs</emphasis>. Multiple mount-points of
+ <emphasis>kdbusfs</emphasis> are independent of each other.
+ This allows namespacing of kdbus by mounting a new instance of
+ <emphasis>kdbusfs</emphasis> in a mount-namespace. kdbus calls
+ these domains and each mount has its own kdbus domain, with
+ each bus being linked to exactly one parent domain.
+ </para>
+
+ <para>
+ Please note that kdbus was designed as transport layer for D-Bus, but is
+ in no way limited, nor controlled by the D-Bus protocol specification.
+ The D-Bus protocol is one possible application layer on top of kdbus.
+ </para>
+
+ <para>
+ For the general D-Bus protocol specification, the payload format, the
+ marshaling, and the communication semantics, please refer to the
+ <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
+ D-Bus specification</ulink>.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Terminology</title>
+
+ <refsect2>
+ <title>Bus</title>
+ <para>
+ A bus is a named object inside a domain. Clients exchange messages
+ over a bus. Multiple buses themselves have no connection to each other;
+ messages can only be exchanged on the same bus. The default endpoint of
+ a bus, to which clients establish connections to, is the "bus" file
+ /sys/fs/kdbus/<bus name>/bus.
+ Common operating system setups create one "system bus" per system,
+ and one "user bus" for every logged-in user. Applications or services
+ may create their own private buses. The kernel driver does not
+ distinguish between different bus types, they are all handled the same
+ way.
+ See
+ <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Endpoint</title>
+ <para>
+ An endpoint provides a file to talk to a bus. Opening an endpoint
+ creates a new connection to the bus to which the endpoint belongs. All
+ endpoints have unique names and are accessible as files underneath the
+ directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint>
+ Every bus has a default endpoint called "bus".
+ A bus can optionally offer additional endpoints with custom names
+ to provide restricted access to the bus. Custom endpoints carry
+ additional policy which can be used to create sandboxes with
+ locked-down, limited, filtered access to a bus.
+ See
+ <citerefentry><refentrytitle>kdbus.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Connection</title>
+ <para>
+ A connection to a bus is created by opening an endpoint file of a
+ bus and becoming an active client with the <varname>HELLO</varname>
+ exchange. Every ordinary client connection has a unique identifier on
+ the bus and can address messages to every other connection on the same
+ bus by using the peer's connection ID as the destination.
+ See
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Pool</title>
+ <para>
+ Each connection allocates a piece of shmem-backed memory that is
+ used to receive messages and answers to ioctl commands from the kernel.
+ It is never used to send anything to the kernel. In order to access that
+ memory, a userspace application must mmap() it into its address space.
+ See section 12 for more details.
+ See
+ <citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Well-known Name</title>
+ <para>A connection can, in addition to its implicit unique connection ID, request
+ the ownership of a textual well-known name. Well-known names are noted in
+ reverse-domain notation, such as com.example.service1. A connection that
+ offers a service on a bus is usually reached by its well-known name. The
+ analogy of connection ID and well-known name is an IP address and a DNS
+ name associated with that address.
+ See
+ <citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Message</title>
+ <para>
+ Connections can exchange messages with other connections by addressing
+ the peers with their connection ID or well-known name. A message consists
+ of a message header with information on how to route the message, and the
+ message payload, which is a logical byte stream of arbitrary size.
+ Messages can carry additional file descriptors to be passed from one
+ connection to another, just like passing file descriptors over UNIX domain
+ sockets. Every connection can specify which set of metadata the kernel
+ should attach to the message when it is delivered to the receiving
+ connection. Metadata contains information like: system timestamps, UID, GID,
+ TID, proc-starttime, well-known names, process comm, process exe, process
+ argv, cgroup, capabilities, seclabel, audit session, loginuid and the
+ connection's human-readable name. See section 7 and 13 for more details.
+ See
+ <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Item</title>
+ <para>
+ The API of kdbus implements the notion of items, submitted through and
+ returned by most ioctls, and stored inside data structures in the
+ connection's pool. See section 4 for more details.
+ See
+ <citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Broadcast, signal, filter, match</title>
+ <para>
+ Signals are messages that a receiver opts in for by installing a blob of
+ bytes, called a 'match'. Signal messages must always carry a 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
+ <citerefentry><refentrytitle>kdbus.match</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
+ <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Policy</title>
+ <para>
+ A policy is a set of rules that define which connections can see, talk to,
+ or register a well-known name on the bus. A policy is attached to buses and
+ custom endpoints, and modified by policy holder connections or owners of
+ custom endpoints. See section 11 for more details.
+ See
+ <citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Privileged bus users</title>
+ <para>
+ A user connecting to the bus is considered privileged if it is either the
+ creator of the bus, or if it has the CAP_IPC_OWNER capability flag set.
+ See
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more details.
+ </para>
+ </refsect2>
+
+ </refsect1>
+
+ <refsect1>
+ <title>The ioctl interface</title>
+
+ <para>kdbus exposes its functions exclusively through
+ <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ through file descriptors returned by
+ <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ on pseudo files exposed by
+ <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
+ </para>
+ <para>
+ Following is a list of all the ioctls.
+ </para>
+ <programlisting>
+0x40209500 KDBUS_CMD_BUS_MAKE struct kdbus_cmd_make *
+0x40209510 KDBUS_CMD_ENDPOINT_MAKE struct kdbus_cmd_make *
+0xc0689520 KDBUS_CMD_HELLO struct kdbus_cmd_hello *
+0x00009521 KDBUS_CMD_BYEBYE
+0xc0489530 KDBUS_CMD_SEND struct kdbus_cmd_send *
+0xc0489531 KDBUS_CMD_RECV struct kdbus_cmd_recv *
+0x40289532 KDBUS_CMD_FREE struct kdbus_cmd_free *
+0xc0209540 KDBUS_CMD_NAME_ACQUIRE struct kdbus_cmd_name *
+0x40209541 KDBUS_CMD_NAME_RELEASE struct kdbus_cmd_name *
+0xc0309542 KDBUS_CMD_NAME_LIST struct kdbus_cmd_name_list *
+0xc0389550 KDBUS_CMD_CONN_INFO struct kdbus_cmd_info *
+0x40209551 KDBUS_CMD_CONN_UPDATE struct kdbus_cmd_update *
+0xc0389552 KDBUS_CMD_BUS_CREATOR_INFO struct kdbus_cmd_info *
+0x40209561 KDBUS_CMD_ENDPOINT_UPDATE struct kdbus_cmd_update *
+0x40289570 KDBUS_CMD_MATCH_ADD struct kdbus_cmd_match *
+0x40289571 KDBUS_CMD_MATCH_REMOVE struct kdbus_cmd_match *
+ </programlisting>
+
+ <para>
+ These ioctls, along with the structs they transport, are explained in
+ detail in the other documents linked to in the 'see also' section below.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Data structures and interconnections</title>
+ <programlisting><![CDATA[
+ +--------------------------------------------------------------------------+
+ | Domain (Mount Point) |
+ | /sys/fs/kdbus/control |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (System Bus) | |
+ | | /sys/fs/kdbus/0-system/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/0-system/bus | | /sys/fs/kdbus/0-system/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | +----------------------------------------------------------------------+ |
+ | |
+ | +----------------------------------------------------------------------+ |
+ | | Bus (User Bus for UID 2702) | |
+ | | /sys/fs/kdbus/2702-user/ | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | | Endpoint | | Endpoint | | |
+ | | | /sys/fs/kdbus/2702-user/bus | | /sys/fs/kdbus/2702-user/ep.app | | |
+ | | +-------------------------------+ +--------------------------------+ | |
+ | | +--------------+ +--------------+ +--------------+ +---------------+ | |
+ | | | Connection | | Connection | | Connection | | Connection | | |
+ | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | |
+ | | +--------------+ +--------------+ +--------------------------------+ | |
+ | +----------------------------------------------------------------------+ |
+ +--------------------------------------------------------------------------+
+ ]]></programlisting>
+ </refsect1>
+
+ <refsect1>
+ <title>Bus Layout</title>
+
+ <para>A bus
+ (<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+ provides and defines an environment that peers can connect to
+ for message interchange. A bus is created via the kdbus
+ control interface and can be modified by the bus creator. It
+ applies the policy that control all bus operations. The bus
+ creator itself does not participate as a peer.
+ To establish a peer connection
+ (<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+ you have to open one of the endpoints
+ (<citerefentry><refentrytitle>kdbus.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+ of a bus. Each bus provides a default endpoint, but further
+ endpoints can be created on-demand. Endpoints are used to apply
+ additional policies for all connections on this endpoint. Thus,
+ they provide additional filters to further restrict access of
+ specific connections to the bus.
+ </para>
+
+ <para>
+ Following, you can see an example bus layout:
+ </para>
+
+ <programlisting><![CDATA[
+ Bus Creator
+ |
+ |
+ +-----+
+ | Bus |
+ +-----+
+ |
+ __________________________/ \__________________________
+ / \
+ | |
+ +----------+ +----------+
+ | Endpoint | | Endpoint |
+ +----------+ +----------+
+ _________/|\_________ _________/|\_________
+ / | \ / | \
+ | | | | | |
+ | | | | | |
+ Connection Connection Connection Connection Connection Connection
+ ]]></programlisting>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Metadata</title>
+ <para>
+ kdbus records data about the system in certain situations. Such metadata
+ can refer to the currently active process (creds, PIDs, current user
+ groups, process names and its executable path, cgroup membership,
+ capabilities, security label and audit information), connection
+ information (description string, currently owned names) and timestamps.
+ </para>
+ <para>
+ Metadata is collected in the following circumstances.
+ </para>
+
+ <itemizedlist mark='opencircle'>
+ <listitem><para>
+ When a bus is created (<varname>KDBUS_CMD_MAKE</varname>), information
+ about the calling task is collected. This data is returned by the
+ kernel via the <varname>KDBUS_CMD_BUS_CREATOR_INFO</varname> call.
+ </para></listitem>
+
+ <listitem><para>
+ When a connection is created (<varname>KDBUS_CMD_HELLO</varname>),
+ information about the calling task is collected. Alternatively, a
+ privileged connection may provide 'faked' information about credentials,
+ PIDs and security labels which will be taken instead. This data is
+ returned by the kernel as information on a connection
+ (<varname>KDBUS_CMD_CONN_INFO</varname>).
+ </para></listitem>
+
+ <listitem><para>
+ When a message is sent (<varname>KDBUS_CMD_SEND</varname>), information
+ about the sending task and the sending connection are collected.
+ This metadata will be attached to the message when it arrives in the
+ receiver's pool. If the connection sending the message installed faked
+ credentials (see
+ <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+ the message will not be augmented by any information about the
+ currently sending task.
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ Which metadata items are actually delivered depends on the following
+ sets and masks:
+ </para>
+
+ <itemizedlist mark='none'>
+ <listitem><para>
+ (a) the system-wide kmod creds mask
+ (module parameter <varname>attach_flags_mask</varname>)
+ </para></listitem>
+
+ <listitem><para>
+ (b) the per-connection send creds mask, set by the connecting client
+ </para></listitem>
+
+ <listitem><para>
+ (c) the per-connection receive creds mask, set by the connecting client
+ </para></listitem>
+
+ <listitem><para>
+ (d) the per-bus minimal creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (e) the per-bus owner creds mask, set by the bus creator
+ </para></listitem>
+
+ <listitem><para>
+ (f) the mask specified when querying creds of a bus peer
+ </para></listitem>
+
+ <listitem><para>
+ (g) the mask specified when querying creds of a bus owner
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ With the following rules:
+ </para>
+
+ <itemizedlist mark='none'>
+ <listitem><para>
+ [1] The creds attached to messages are determined as
+ (a & b & c).
+ </para></listitem>
+
+ <listitem><para>
+ [2] When connecting to a bus (<varname>KDBUS_CMD_HELLO</varname>), and
+ (~b & d) != 0, the call will fail, the connection is refused.
+ </para></listitem>
+
+ <listitem><para>
+ [3] When querying creds of a bus peer, the creds returned are
+ (a & b & f)
+ </para></listitem>
+
+ <listitem><para>
+ [4] When querying creds of a bus owner, the creds returned are
+ (a & e & g)
+ </para></listitem>
+
+ <listitem><para>
+ [5] When creating a new bus, and (d & ~a) != 0, then bus creation
+ will fail
+ </para></listitem>
+ </itemizedlist>
+
+ <para>
+ Hence, userspace might not always get all requested metadata items that
+ it requested. Code must be written so that it can cope with this fact.
+ </para>
+
+ <refsect2>
+ <title>Known metadata item types</title>
+ <para>
+ To let the kernel know which metadata information to attach as items
+ to the afformentioned commands, it uses a bitmask. In those, the
+ following <emphasis>attach flags</emphasis> are currently supported.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_TIMESTAMP</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_TIMESTAMP</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_CREDS</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_CREDS</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_PIDS</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_PIDS</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_AUXGROUPS</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_AUXGROUPS</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_NAMES</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_OWNED_NAME</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_TID_COMM [*]</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_TID_COMM</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_PID_COMM [*]</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_PID_COMM</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_EXE [*]</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_EXE</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_CMDLINE</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_CMDLINE</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_CGROUP</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_CGROUP</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_CAPS</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_CAPS</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_SECLABEL</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_SECLABEL</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_AUDIT</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_AUDIT</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KDBUS_ATTACH_CONN_DESCRIPTION</varname></term>
+ <listitem><para>
+ Requests the attachment of an item of type
+ <varname>KDBUS_ITEM_CONN_DESCRIPTION</varname>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ Please refer to
+ <citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for detailed information about the layout any payload of items.
+ </para>
+
+ <para>
+ [*] Note that the content stored in these items can easily be tampered
+ by the sending tasks. Therefore, they should <emphasis>not</emphasis>
+ be used for any sort of security relevant assumptions. The only reason
+ why they are transmitted is to let receivers know about details that
+ were set when metadata was collected, even though the task they were
+ collected from is not active any longer when the items are received.
+ </para>
+ </refsect2>
+
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <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.message</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
+ <member><ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink></member>
+ </simplelist>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <param name="chunk.quietly">1</param>
+ <param name="funcsynopsis.style">ansi</param>
+ <param name="funcsynopsis.tabular.threshold">80</param>
+ <param name="callout.graphics">0</param>
+ <param name="paper.type">A4</param>
+ <param name="generate.section.toc.level">2</param>
+ <param name="use.id.as.filename">1</param>
+ <param name="citerefentry.link">1</param>
+ <strip-space elements="*"/>
+ <template name="generate.citerefentry.link">
+ <value-of select="refentrytitle"/>
+ <text>.html</text>
+ </template>
+</stylesheet>
projects / platform / core / system / kdbus-bus.git / commitdiff