subdir-y := accounting auxdisplay blackfin connector \
- filesystems filesystems ia64 kdbus laptops mic misc-devices \
+ filesystems filesystems ia64 laptops mic misc-devices \
networking pcmcia prctl ptp spi timers vDSO video4linux \
watchdog
+++ /dev/null
-DOCS := \
- kdbus.xml \
- kdbus.bus.xml \
- kdbus.connection.xml \
- kdbus.endpoint.xml \
- kdbus.fs.xml \
- kdbus.item.xml \
- kdbus.match.xml \
- kdbus.message.xml \
- kdbus.name.xml \
- kdbus.policy.xml \
- kdbus.pool.xml
-
-XMLFILES := $(addprefix $(obj)/,$(DOCS))
-MANFILES := $(patsubst %.xml, %.7, $(XMLFILES))
-HTMLFILES := $(patsubst %.xml, %.html, $(XMLFILES))
-
-XMLTO_ARGS := -m $(obj)/stylesheet.xsl
-
-%.7: %.xml
- xmlto man $(XMLTO_ARGS) -o . $<
-
-%.html: %.xml
- xmlto html-nochunks $(XMLTO_ARGS) -o . $<
-
-mandocs: $(MANFILES)
-
-htmldocs: $(HTMLFILES)
-
-clean-files := $(MANFILES) $(HTMLFILES)
+++ /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 <constant>bus</constant> 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, the name that is passed in must be properly formatted, or
- the kernel will refuse creation of the bus. Example:
- <literal>1047-foobar</literal> is an acceptable name for a bus
- registered by a user with UID 1047. However,
- <literal>1024-foobar</literal> is not, and neither is
- <literal>foobar</literal>. The UID must be provided in the
- user-namespace of the bus owner.
- </para>
- <para>
- To create a new bus, you need to open the control file of a domain and
- employ the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl. The control
- file descriptor that was used to issue
- <constant>KDBUS_CMD_BUS_MAKE</constant> 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
- <citerefentry>
- <refentrytitle>close</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- .
- </para>
- <para>
- Each bus will generate a random, 128-bit UUID upon creation. This UUID
- will be returned to creators of connections through
- <varname>kdbus_cmd_hello.id128</varname> and can be used to uniquely
- identify buses, even across different machines or containers. The UUID
- will have its variant bits set to <literal>DCE</literal>, and denote
- version 4 (random). For more details on UUIDs, see <ulink
- url="https://en.wikipedia.org/wiki/Universally_unique_identifier">
- the Wikipedia article on UUIDs</ulink>.
- </para>
-
- </refsect1>
-
- <refsect1>
- <title>Creating buses</title>
- <para>
- To create a new bus, the <constant>KDBUS_CMD_BUS_MAKE</constant>
- command is used. It takes a <type>struct kdbus_cmd</type> argument.
- </para>
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 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><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
- <listitem>
- <para>Make the bus file group-accessible.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
- <listitem>
- <para>Make the bus file world-accessible.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- The following items (see
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- ) are expected for <constant>KDBUS_CMD_BUS_MAKE</constant>.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
- <listitem>
- <para>
- Contains a null-terminated string that identifies the
- bus. The name must be unique across the kdbus domain and
- must start with the effective UID of the caller, followed by
- a '<literal>-</literal>' (dash). This item is mandatory.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
- <listitem>
- <para>
- Bus-wide bloom parameters passed in a
- <type>struct kdbus_bloom_parameter</type>. These settings are
- copied back to new connections verbatim. This item is
- mandatory. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for a more detailed description of this item.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></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><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></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>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EBADMSG</constant></term>
- <listitem><para>
- A mandatory item is missing.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- The flags supplied in the <constant>struct kdbus_cmd</constant>
- are invalid or the supplied name does not start with the current
- UID and a '<literal>-</literal>' (dash).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EEXIST</constant></term>
- <listitem><para>
- A bus of that name already exists.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ESHUTDOWN</constant></term>
- <listitem><para>
- The kdbus mount instance for the bus was already shut down.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMFILE</constant></term>
- <listitem><para>
- The maximum number of buses for the current user is exhausted.
- </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.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.name</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 <type>uint64_t</type> counter.
- The IDs of every newly created bus start at <constant>1</constant>, and
- every new connection will increment the counter by <constant>1</constant>.
- 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
- <constant>":1.<ID>"</constant>.
- </para>
- <para>
- Messages with a specific <type>uint64_t</type> destination ID are
- directly delivered to the connection with the corresponding ID. Signal
- messages (see
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>)
- may be addressed to the special destination ID
- <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) and will then
- potentially be delivered to all currently active connections on the bus.
- However, in order to receive any signal messages, clients must subscribe
- to them by installing a match (see
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- ).
- </para>
- <para>
- Messages synthesized and sent directly by the kernel will carry the
- special source ID <constant>KDBUS_SRC_ID_KERNEL</constant> (0).
- </para>
- <para>
- In addition to the unique <type>uint64_t</type> 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.name</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
- <constant>KDBUS_DST_ID_NAME</constant> (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>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 <constant>CAP_IPC_OWNER</constant> set when it called
- <constant>KDBUS_CMD_HELLO</constant> (see below).
- </para>
- <para>
- Privileged connections have permission to employ certain restricted
- functions and commands, which are explained below and in other kdbus
- man-pages.
- </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 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 or policy holder connections is restricted to
- privileged users on the bus (see above).
- </para>
- </refsect1>
-
- <refsect1>
- <title>Monitor connections</title>
- <para>
- Monitors are eavesdropping connections that receive all the traffic on the
- bus, but is invisible to other connections. Such connections have all
- properties of any other, regular connection, except for the following
- details:
- </para>
-
- <itemizedlist>
- <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>
- They cannot own well-known names. Therefore, they also can't operate as
- activators.
- </para></listitem>
-
- <listitem><para>
- Their creation and destruction will not cause
- <constant>KDBUS_ITEM_ID_{ADD,REMOVE}</constant> (see
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>).
- </para></listitem>
-
- <listitem><para>
- They are not listed with their unique name in name registry dumps
- (see <constant>KDBUS_CMD_NAME_LIST</constant> in
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>), so other connections cannot detect the presence of
- a monitor.
- </para></listitem>
- </itemizedlist>
- <para>
- The creation of monitor connections is restricted to privileged users on
- the bus (see above).
- </para>
- </refsect1>
-
- <refsect1>
- <title>Creating connections</title>
- <para>
- A connection to a bus is created by opening an endpoint file (see
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>)
- of a bus and becoming an active client with the
- <constant>KDBUS_CMD_HELLO</constant> ioctl. Every 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 <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
- kdbus_cmd_hello</type> as argument.
- </para>
-
- <programlisting>
-struct kdbus_cmd_hello {
- __u64 size;
- __u64 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><constant>KDBUS_HELLO_ACCEPT_FD</constant></term>
- <listitem>
- <para>
- When this flag is set, the connection can be sent file
- descriptors as message payload of unicast messages. If it's
- not set, an attempt to send file descriptors will result in
- <constant>-ECOMM</constant> on the sender's side.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_HELLO_ACTIVATOR</constant></term>
- <listitem>
- <para>
- Make this connection an activator (see above). With this bit
- set, an item of type <constant>KDBUS_ITEM_NAME</constant> has
- to be attached. This item describes the well-known name this
- connection should be an activator for.
- A connection can not be an activator and a policy holder at
- the same time time, so this bit is not allowed together with
- <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_HELLO_POLICY_HOLDER</constant></term>
- <listitem>
- <para>
- Make this connection a policy holder (see above). With this
- bit set, an item of type <constant>KDBUS_ITEM_NAME</constant>
- has to be attached. This item describes the well-known name
- this connection should hold a policy for.
- A connection can not be an activator and a policy holder at
- the same time time, so this bit is not allowed together with
- <constant>KDBUS_HELLO_ACTIVATOR</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_HELLO_MONITOR</constant></term>
- <listitem>
- <para>
- Make this connection a monitor connection (see above).
- </para>
- <para>
- This flag can only be set by privileged bus connections. See
- below for more information.
- A connection can not be monitor and an activator or a policy
- holder at the same time time, so this bit is not allowed
- together with <constant>KDBUS_HELLO_ACTIVATOR</constant> or
- <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>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 be attached
- to the message. Note, however, that the bus may optionally require
- some of those bits to be set. If the match fails, the ioctl will fail
- with <varname>errno</varname> set to
- <constant>ECONNREFUSED</constant>. In either case, when returning the
- field will be set to the mask of metadata items that are enforced by
- the bus with the <constant>KDBUS_FLAGS_KERNEL</constant> bit set as
- well.
- </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
- <citerefentry>
- <refentrytitle>kdbus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for information about metadata, and
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- regarding items in general.
- </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
- <constant>KDBUS_CMD_HELLO</constant> ioctl.
- The pool size of a connection must be greater than
- <constant>0</constant> and a multiple of
- <constant>PAGE_SIZE</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more 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><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
- <listitem>
- <para>
- Contains a string that describes this connection, so it can
- be identified later.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
- <listitem>
- <para>
- For activators and policy holders only, combinations of
- these two items describe policy access entries. See
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further details.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CREDS</constant></term>
- <term><constant>KDBUS_ITEM_PIDS</constant></term>
- <term><constant>KDBUS_ITEM_SECLABEL</constant></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
- <constant>KDBUS_CMD_CONN_INFO</constant>. See below for more
- information on retrieving information on connections.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- At the offset returned in the <varname>offset</varname> field of
- <type>struct kdbus_cmd_hello</type>, the kernel will store items
- of the following types:
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></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
- <constant>KDBUS_CMD_FREE</constant> ioctl. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further information.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Retrieving information on a connection</title>
- <para>
- The <constant>KDBUS_CMD_CONN_INFO</constant> 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 return_flags;
- __u64 id;
- __u64 attach_flags;
- __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>
- Currently, no flags are supported.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
- and the <varname>flags</varname> field is set to
- <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>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
- <constant>KDBUS_ITEM_OWNED_NAME</constant> item is ignored.
- </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>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 further information.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>info_size</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 further information.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- The following items are expected for
- <constant>KDBUS_CMD_CONN_INFO</constant>.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_OWNED_NAME</constant></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>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- 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
- <type>struct kdbus_cmd_info</type>, items of types
- <constant>KDBUS_ITEM_OWNED_NAME</constant> and
- <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant> may follow here.
- <constant>KDBUS_ITEM_NEGOTIATE</constant> is also allowed.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Once the caller is finished with parsing the return buffer, it needs to
- employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
- order to free the buffer part. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further information.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Getting information about a connection's bus creator</title>
- <para>
- The <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> ioctl takes the same
- struct as <constant>KDBUS_CMD_CONN_INFO</constant>, 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 <type>struct kdbus_info</type>,
- pointed to by the ioctl's <varname>offset</varname> field.
- </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 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 <constant>KDBUS_ITEM_MAKE_NAME</constant> item that
- indicates the bus name of the calling connection.
- <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed to probe
- for known item types.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Once the caller is finished with parsing the return buffer, it needs to
- employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
- order to free the buffer part. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further information.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Updating connection details</title>
- <para>
- Some of a connection's details can be updated with the
- <constant>KDBUS_CMD_CONN_UPDATE</constant> ioctl, using the file
- descriptor that was used to create the connection. The update command
- uses the following struct.
- </para>
-
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 flags;
- __u64 return_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.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
- and the <varname>flags</varname> field is set to
- <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items to describe the connection details to be updated. The
- following item types are supported.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
- <listitem>
- <para>
- Supply a new set of metadata items that this connection
- permits to be sent along with messages.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
- <listitem>
- <para>
- Supply a new set of metadata items that this connection
- requests to be attached to each message.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
- <listitem>
- <para>
- Policy holder connections may supply a new set of policy
- information with these items. For other connection types,
- <constant>EOPNOTSUPP</constant> is returned in
- <varname>errno</varname>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </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
- <constant>KDBUS_CMD_BYEBYE</constant> ioctl. This ioctl will succeed only
- if the message queue of the connection is empty at the time of closing;
- otherwise, the ioctl will fail with <varname>errno</varname> set to
- <constant>EBUSY</constant>. 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. The ioctl takes an argument of
- type <type>struct kdbus_cmd</type>.
- </para>
-
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 flags;
- __u64 return_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.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will fail with
- <varname>errno</varname> set to <constant>EPROTO</constant>, and
- the <varname>flags</varname> field is set to <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items to describe the connection details to be updated. The
- following item types are supported.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_HELLO</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EFAULT</constant></term>
- <listitem><para>
- The supplied pool size was 0 or not a multiple of the page size.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- The flags supplied in <type>struct kdbus_cmd_hello</type>
- are invalid.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- An illegal combination of
- <constant>KDBUS_HELLO_MONITOR</constant>,
- <constant>KDBUS_HELLO_ACTIVATOR</constant> and
- <constant>KDBUS_HELLO_POLICY_HOLDER</constant> was passed in
- <varname>flags</varname>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- An invalid set of items was supplied.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ECONNREFUSED</constant></term>
- <listitem><para>
- The attach_flags_send field did not satisfy the requirements of
- the bus.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EPERM</constant></term>
- <listitem><para>
- A <constant>KDBUS_ITEM_CREDS</constant> items was supplied, but the
- current user is not privileged.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ESHUTDOWN</constant></term>
- <listitem><para>
- The bus you were trying to connect to has already been shut down.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMFILE</constant></term>
- <listitem><para>
- The maximum number of connections on the bus has been reached.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EOPNOTSUPP</constant></term>
- <listitem><para>
- The endpoint does not support the connection flags supplied in
- <type>struct kdbus_cmd_hello</type>.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EALREADY</constant></term>
- <listitem><para>
- The connection has already been shut down.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EBUSY</constant></term>
- <listitem><para>
- There are still messages queued up in the connection's pool.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Invalid flags, or neither an ID nor a name was provided, or the
- name is invalid.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ESRCH</constant></term>
- <listitem><para>
- Connection lookup by name failed.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ENXIO</constant></term>
- <listitem><para>
- No connection with the provided connection ID found.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal flags or items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Wildcards submitted in policy entries, or illegal sequence
- of policy items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EOPNOTSUPP</constant></term>
- <listitem><para>
- Operation not supported by connection.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>E2BIG</constant></term>
- <listitem><para>
- Too many policy items attached.
- </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.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.item</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
- (<literal>bus</literal>) and use the
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> ioctl with
- <type>struct kdbus_cmd</type>. 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 <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> 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:
- <literal>1047-my-endpoint</literal> is an acceptable name for an
- endpoint registered by a user with UID 1047. However,
- <literal>1024-my-endpoint</literal> is not, and neither is
- <literal>my-endpoint</literal>. The UID must be provided in the
- user-namespace of the bus.
- </para>
- <para>
- To create connections to a bus, use <constant>KDBUS_CMD_HELLO</constant>
- on a file descriptor returned by <function>open()</function> 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
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> command is used. Along with
- the endpoint's name, which will be used to expose the endpoint in the
- <citerefentry>
- <refentrytitle>kdbus.fs</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>,
- the command also optionally takes items to set up the endpoint's
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> takes a
- <type>struct kdbus_cmd</type> argument.
- </para>
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 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><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
- <listitem>
- <para>Make the endpoint file group-accessible.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
- <listitem>
- <para>Make the endpoint file world-accessible.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- The following items are expected for
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
- <listitem>
- <para>Contains a string to identify the endpoint name.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
- <listitem>
- <para>
- These items are used to set the policy attached to the
- endpoint. For more details on bus and endpoint policies, see
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <varname>EINVAL</varname>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Updating endpoints</title>
- <para>
- To update an existing endpoint, the
- <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file
- descriptor that was used to create the update, using
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. The only relevant detail of
- the endpoint that can be updated is the policy. When the command is
- employed, the policy of the endpoint is <emphasis>replaced</emphasis>
- atomically with the new set of rules.
- The command takes a <type>struct kdbus_cmd</type> argument.
- </para>
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 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>
- Unused for this command.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
- and the <varname>flags</varname> field is set to
- <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- The following items are expected for
- <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
- <listitem>
- <para>
- These items are used to set the policy attached to the
- endpoint. For more details on bus and endpoint policies, see
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- Existing policy is atomically replaced with the new rules
- provided.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> may fail with the
- following errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- The flags supplied in the <type>struct kdbus_cmd</type>
- are invalid.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
- <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EEXIST</constant></term>
- <listitem><para>
- An endpoint of that name already exists.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EPERM</constant></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>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the
- following errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- The flags supplied in <type>struct kdbus_cmd</type>
- are invalid.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and
- <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EEXIST</constant></term>
- <listitem><para>
- An endpoint of that name already exists.
- </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.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.name</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 filesystem provides access to
- kdbus entities, such as <emphasis>buses</emphasis> and
- <emphasis>endpoints</emphasis>. Each time the filesystem is mounted,
- a new, isolated kdbus instance is created, which is independent from the
- other instances.
- </para>
- <para>
- The system-wide standard mount point for <emphasis>kdbusfs</emphasis> is
- <constant>/sys/fs/kdbus</constant>.
- </para>
-
- <para>
- Buses are represented as directories in the file system layout, whereas
- endpoints are exposed as files inside these directories. At the top-level,
- a <emphasis>control</emphasis> node is present, which can be opened to
- create new buses via the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl.
- Each <emphasis>bus</emphasis> shows a default endpoint called
- <varname>bus</varname>, which can be opened to either create a connection
- with the <constant>KDBUS_CMD_HELLO</constant> ioctl, or to create new
- custom endpoints for the bus with
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry> and
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para>
-
- <para>Following, you can see an example layout of the
- <emphasis>kdbusfs</emphasis> filesystem:</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, a new instance
- of <emphasis>kdbusfs</emphasis> can be mounted like this:
- </para>
-<programlisting>
- # mount -t kdbusfs kdbusfs /tmp/new_kdbus/
-</programlisting>
- </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>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>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>kdbus.item</refname>
- <refpurpose>kdbus item structure, layout and usage</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>
- To flexibly augment transport structures, data blobs of type
- <type>struct kdbus_item</type> 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
- attached to will cause the ioctl to fail with <varname>errno</varname>
- set to <constant>EINVAL</constant>.
- 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.
- </para>
-
- <refsect2>
- <title>Chaining items</title>
- <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, and an item iterator
- (see below) is capable of detecting the end of an item chain.
- </para>
- </refsect2>
-
- <refsect2>
- <title>Alignment</title>
- <para>
- The kernel expects all items to be aligned to 8-byte boundaries.
- Unaligned items will cause the ioctl they are used with to fail
- with <varname>errno</varname> set to <constant>EINVAL</constant>.
- An item that has an unaligned size itself hence needs to be padded
- if it is followed by another item.
- </para>
- </refsect2>
-
- <refsect2>
- <title>Iterating items</title>
- <para>
- A simple iterator 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(val) (((val) + 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_t *)(head)); \
- item = KDBUS_ITEM_NEXT(item))
- ]]></programlisting>
- </refsect2>
- </refsect1>
-
- <refsect1>
- <title>Item layout</title>
- <para>
- A <type>struct kdbus_item</type> 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.
- The struct layout is shown below.
- </para>
-
- <programlisting>
-struct kdbus_item {
- __u64 size;
- __u64 type;
- /* item payload - see below */
- union {
- __u8 data[0];
- __u32 data32[0];
- __u64 data64[0];
- char str[0];
-
- __u64 id;
- struct kdbus_vec vec;
- struct kdbus_creds creds;
- struct kdbus_pids pids;
- struct kdbus_audit audit;
- struct kdbus_caps caps;
- struct kdbus_timestamp timestamp;
- struct kdbus_name name;
- struct kdbus_bloom_parameter bloom_parameter;
- struct kdbus_bloom_filter bloom_filter;
- struct kdbus_memfd memfd;
- int fds[0];
- struct kdbus_notify_name_change name_change;
- struct kdbus_notify_id_change id_change;
- struct kdbus_policy_access policy_access;
- };
-};
- </programlisting>
-
- <para>
- <type>struct kdbus_item</type> 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>
- </refsect1>
-
- <refsect1>
- <title>Item types</title>
-
- <refsect2>
- <title>Negotiation item</title>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item is attached to any ioctl, programs can
- <emphasis>probe</emphasis> the kernel for known item items.
- The item carries an array of <type>uint64_t</type> values in
- <varname>item.data64</varname>, each set to an item type to
- probe. The kernel will reset each member of this array that is
- not recognized as valid item type to <constant>0</constant>.
- This way, users can negotiate kernel features at start-up to
- keep newer userspace compatible with older kernels. This item
- is never attached by the kernel in response to any command.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>Command specific items</title>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
- <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
- <listitem><para>
- Messages are directly copied by the sending process into the
- receiver's
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- 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. <constant>KDBUS_ITEM_PAYLOAD_VEC</constant>
- is used when <emphasis>sending</emphasis> message. The item
- references a memory address when the payload data can be found.
- <constant>KDBUS_ITEM_PAYLOAD_OFF</constant> is used when messages
- are <emphasis>received</emphasis>, and the
- <constant>offset</constant> value describes the offset inside the
- receiving connection's
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- where the message payload can be found. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on passing of payload data along with a
- message.
- <programlisting>
-struct kdbus_vec {
- __u64 size;
- union {
- __u64 address;
- __u64 offset;
- };
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
- <listitem><para>
- Transports a file descriptor of a <emphasis>memfd</emphasis> in
- <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
- The <varname>size</varname> field has to match the actual size of
- the memfd that was specified when it was created. The
- <varname>start</varname> parameter denotes the offset inside the
- memfd at which the referenced payload starts. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on passing of payload data along with a
- message.
- <programlisting>
-struct kdbus_memfd {
- __u64 start;
- __u64 size;
- int fd;
- __u32 __pad;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_FDS</constant></term>
- <listitem><para>
- Contains an array of <emphasis>file descriptors</emphasis>.
- When used with <constant>KDBUS_CMD_SEND</constant>, the values of
- this array must be filled with valid file descriptor numbers.
- When received as item attached to a message, the array will
- contain the numbers of the installed file descriptors, or
- <constant>-1</constant> in case an error occurred.
- file descriptor.
- In either case, the number of entries in the array is derived from
- the item's total size. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>Items specific to some commands</title>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
- <listitem><para>
- Transports a file descriptor that can be used to cancel a
- synchronous <constant>KDBUS_CMD_SEND</constant> operation by
- writing to it. The file descriptor is stored in
- <varname>item.fd[0]</varname>. The item may only contain one
- file descriptor. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on this item and how to use it.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
- <listitem><para>
- Contains a set of <emphasis>bloom parameters</emphasis> as
- <type>struct kdbus_bloom_parameter</type> in
- <varname>item.bloom_parameter</varname>.
- The item is passed from userspace to kernel during the
- <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl, and returned
- verbatim when <constant>KDBUS_CMD_HELLO</constant> is called.
- The kernel does not use the bloom parameters, but they need to
- be known by each connection on the bus in order to define the
- bloom filter hash details. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on matching and bloom filters.
- <programlisting>
-struct kdbus_bloom_parameter {
- __u64 size;
- __u64 n_hash;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
- <listitem><para>
- Carries a <emphasis>bloom filter</emphasis> as
- <type>struct kdbus_bloom_filter</type> in
- <varname>item.bloom_filter</varname>. It is mandatory to send this
- item attached to a <type>struct kdbus_msg</type>, in case the
- message is a signal. This item is never transported from kernel to
- userspace. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on matching and bloom filters.
- <programlisting>
-struct kdbus_bloom_filter {
- __u64 generation;
- __u64 data[0];
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
- <listitem><para>
- Transports a <emphasis>bloom mask</emphasis> as binary data blob
- stored in <varname>item.data</varname>. This item is used to
- describe a match into a connection's match database. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on matching and bloom filters.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
- <listitem><para>
- Contains a <emphasis>well-known name</emphasis> to send a
- message to, as null-terminated string in
- <varname>item.str</varname>. This item is used with
- <constant>KDBUS_CMD_SEND</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on how to send a message.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
- <listitem><para>
- Contains a <emphasis>bus name</emphasis> or
- <emphasis>endpoint name</emphasis>, stored as null-terminated
- string in <varname>item.str</varname>. This item is sent from
- userspace to kernel when buses or endpoints are created, and
- returned back to userspace when the bus creator information is
- queried. See
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
- <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
- <listitem><para>
- Contains a set of <emphasis>attach flags</emphasis> at
- <emphasis>send</emphasis> or <emphasis>receive</emphasis> time. See
- <citerefentry>
- <refentrytitle>kdbus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>,
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry> and
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on attach flags.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ID</constant></term>
- <listitem><para>
- Transports a connection's <emphasis>numerical ID</emphasis> of
- a connection as <type>uint64_t</type> value in
- <varname>item.id</varname>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <listitem><para>
- Transports a name associated with the
- <emphasis>name registry</emphasis> as null-terminated string as
- <type>struct kdbus_name</type> in
- <varname>item.name</varname>. The <varname>flags</varname>
- contains the flags of the name. See
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on how to access the name registry of a bus.
- <programlisting>
-struct kdbus_name {
- __u64 flags;
- char name[0];
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>Items attached by the kernel as metadata</title>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_TIMESTAMP</constant></term>
- <listitem><para>
- Contains both the <emphasis>monotonic</emphasis> and the
- <emphasis>realtime</emphasis> timestamp, taken when the message
- was processed on the kernel side.
- Stored as <type>struct kdbus_timestamp</type> in
- <varname>item.timestamp</varname>.
- <programlisting>
-struct kdbus_timestamp {
- __u64 seqnum;
- __u64 monotonic_ns;
- __u64 realtime_ns;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CREDS</constant></term>
- <listitem><para>
- Contains a set of <emphasis>user</emphasis> and
- <emphasis>group</emphasis> information as 32-bit values, in the
- usual four flavors: real, effective, saved and filesystem related.
- Stored as <type>struct kdbus_creds</type> in
- <varname>item.creds</varname>.
- <programlisting>
-struct kdbus_creds {
- __u32 uid;
- __u32 euid;
- __u32 suid;
- __u32 fsuid;
- __u32 gid;
- __u32 egid;
- __u32 sgid;
- __u32 fsgid;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_PIDS</constant></term>
- <listitem><para>
- Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
- and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
- Stored as <type>struct kdbus_pids</type> in
- <varname>item.pids</varname>.
- <programlisting>
-struct kdbus_pids {
- __u64 pid;
- __u64 tid;
- __u64 ppid;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_AUXGROUPS</constant></term>
- <listitem><para>
- Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
- a remote peer is a member of, stored as array of
- <type>uint32_t</type> values in <varname>item.data32</varname>.
- The array length can be determined by looking at the item's total
- size, subtracting the size of the header and and dividing the
- remainder by <constant>sizeof(uint32_t)</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
- <listitem><para>
- Contains a <emphasis>well-known name</emphasis> currently owned
- by a connection. The name is stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
- <listitem><para>
- Contains the <emphasis>comm</emphasis> string of a task's
- <emphasis>TID</emphasis> (thread ID), stored as null-terminated
- string in <varname>item.str</varname>. Its length can also be
- derived from the item's total size. Receivers of this item should
- not use its contents for any kind of security measures. See below.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
- <listitem><para>
- Contains the <emphasis>comm</emphasis> string of a task's
- <emphasis>PID</emphasis> (process ID), stored as null-terminated
- string in <varname>item.str</varname>. Its length can also be
- derived from the item's total size. Receivers of this item should
- not use its contents for any kind of security measures. See below.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
- <listitem><para>
- Contains the <emphasis>path to the executable</emphasis> of a task,
- stored as null-terminated string in <varname>item.str</varname>. Its
- length can also be derived from the item's total size. Receivers of
- this item should not use its contents for any kind of security
- measures. See below.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CMDLINE</constant> [*]</term>
- <listitem><para>
- Contains the <emphasis>command line arguments</emphasis> of a
- task, stored as an <emphasis>array</emphasis> of null-terminated
- strings in <varname>item.str</varname>. The total length of all
- strings in the array can be derived from the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CGROUP</constant></term>
- <listitem><para>
- Contains the <emphasis>cgroup path</emphasis> of a task, stored
- as null-terminated string in <varname>item.str</varname>. Its
- length can also be derived from the item's total size.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CAPS</constant></term>
- <listitem><para>
- Contains sets of <emphasis>capabilities</emphasis>, stored as
- <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
- As the item size may increase in the future, programs should be
- written in a way that it takes
- <varname>item.caps.last_cap</varname> into account, and derive
- the number of sets and rows from the item size and the reported
- number of valid capability bits.
- <programlisting>
-struct kdbus_caps {
- __u32 last_cap;
- __u32 caps[0];
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
- <listitem><para>
- Contains the <emphasis>LSM label</emphasis> of a task, stored as
- null-terminated string in <varname>item.str</varname>. Its length
- can also be derived from the item's total size.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_AUDIT</constant></term>
- <listitem><para>
- Contains the audit <emphasis>sessionid</emphasis> and
- <emphasis>loginuid</emphasis> of a task, stored as
- <type>struct kdbus_audit</type> in
- <varname>item.audit</varname>.
- <programlisting>
-struct kdbus_audit {
- __u32 sessionid;
- __u32 loginuid;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
- <listitem><para>
- Contains the <emphasis>connection description</emphasis>, as set
- by <constant>KDBUS_CMD_HELLO</constant> or
- <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
- null-terminated string in <varname>item.str</varname>. Its length
- can also be derived from the item's total size.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- All metadata is automatically translated into the
- <emphasis>namespaces</emphasis> of the task that receives them. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information.
- </para>
-
- <para>
- [*] Note that the content stored in metadata items of type
- <constant>KDBUS_ITEM_TID_COMM</constant>,
- <constant>KDBUS_ITEM_PID_COMM</constant>,
- <constant>KDBUS_ITEM_EXE</constant> and
- <constant>KDBUS_ITEM_CMDLINE</constant>
- 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 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>
-
- <refsect2>
- <title>Items used for policy entries, matches and notifications</title>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
- <listitem><para>
- This item describes a <emphasis>policy access</emphasis> entry to
- access the policy database of a
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry> or
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- Please refer to
- <citerefentry>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on the policy database and how to access it.
- <programlisting>
-struct kdbus_policy_access {
- __u64 type;
- __u64 access;
- __u64 id;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
- <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
- <listitem><para>
- This item is sent as attachment to a
- <emphasis>kernel notification</emphasis> and indicates that a
- new connection was created on the bus, or that a connection was
- disconnected, respectively. It stores a
- <type>struct kdbus_notify_id_change</type> in
- <varname>item.id_change</varname>.
- The <varname>id</varname> field contains the numeric ID of the
- connection that was added or removed, and <varname>flags</varname>
- is set to the connection flags, as passed by
- <constant>KDBUS_CMD_HELLO</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on matches and notification messages.
- <programlisting>
-struct kdbus_notify_id_change {
- __u64 id;
- __u64 flags;
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
- <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
- <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
- <listitem><para>
- This item is sent as attachment to a
- <emphasis>kernel notification</emphasis> and indicates that a
- <emphasis>well-known name</emphasis> appeared, disappeared or
- transferred to another owner on the bus. It stores a
- <type>struct kdbus_notify_name_change</type> in
- <varname>item.name_change</varname>.
- <varname>old_id</varname> describes the former owner of the name
- and is set to <constant>0</constant> values in case of
- <constant>KDBUS_ITEM_NAME_ADD</constant>.
- <varname>new_id</varname> describes the new owner of the name and
- is set to <constant>0</constant> values in case of
- <constant>KDBUS_ITEM_NAME_REMOVE</constant>.
- The <varname>name</varname> field contains the well-known name the
- notification is about, as null-terminated string. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on matches and notification messages.
- <programlisting>
-struct kdbus_notify_name_change {
- struct kdbus_notify_id_change old_id;
- struct kdbus_notify_id_change new_id;
- char name[0];
-};
- </programlisting>
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_REPLY_TIMEOUT</constant></term>
- <listitem><para>
- This item is sent as attachment to a
- <emphasis>kernel notification</emphasis>. It informs the receiver
- that an expected reply to a message was not received in time.
- The remote peer ID and the message cookie is stored in the message
- header. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information about messages, timeouts and notifications.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_REPLY_DEAD</constant></term>
- <listitem><para>
- This item is sent as attachment to a
- <emphasis>kernel notification</emphasis>. It informs the receiver
- that a remote connection a reply is expected from was disconnected
- before that reply was sent. The remote peer ID and the message
- cookie is stored in the message header. See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information about messages, timeouts and notifications.
- </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.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>memfd_create</refentrytitle>
- <manvolnum>2</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.match">
-
- <refentryinfo>
- <title>kdbus.match</title>
- <productname>kdbus.match</productname>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>kdbus.match</refname>
- <refpurpose>kdbus match</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>
- kdbus connections can install matches in order to subscribe to signal
- messages sent on the bus. Such signal messages can be either directed
- to a single connection (by setting a specific connection ID in
- <varname>struct kdbus_msg.dst_id</varname> or by sending it to a
- well-known name), or to potentially <emphasis>all</emphasis> currently
- active connections on the bus (by setting
- <varname>struct kdbus_msg.dst_id</varname> to
- <constant>KDBUS_DST_ID_BROADCAST</constant>).
- A signal message always has the <constant>KDBUS_MSG_SIGNAL</constant>
- bit set in the <varname>flags</varname> bitfield.
- Also, signal messages can originate from either the kernel (called
- <emphasis>notifications</emphasis>), or from other bus connections.
- In either case, a bus connection needs to have a suitable
- <emphasis>match</emphasis> installed in order to receive any signal
- message. Without any rules installed in the connection, no signal message
- will be received.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Matches for signal messages from other connections</title>
- <para>
- Matches for messages from other connections (not kernel notifications)
- are implemented as bloom filters (see below). The sender adds certain
- properties of the message as elements to a bloom filter bit field, and
- sends that along with the signal message.
-
- The receiving connection adds the message properties it is interested in
- as elements to a bloom mask bit field, and uploads the mask as match rule,
- possibly along with some other rules to further limit the match.
-
- The kernel will match the signal message's bloom filter against the
- connections bloom mask (simply by &-ing it), and will decide whether
- the message should be delivered to a connection.
- </para>
- <para>
- The kernel has no notion of any specific properties of the signal message,
- all it sees are the bit fields of the bloom filter and the mask to match
- against. The use of bloom filters allows simple and efficient matching,
- without exposing any message properties or internals to the kernel side.
- Clients need to deal with the fact that they might receive signal messages
- which they did not subscribe to, as the bloom filter might allow
- false-positives to pass the filter.
-
- To allow the future extension of the set of elements in the bloom filter,
- the filter specifies a <emphasis>generation</emphasis> number. A later
- generation must always contain all elements of the set of the previous
- generation, but can add new elements to the set. The match rules mask can
- carry an array with all previous generations of masks individually stored.
- When the filter and mask are matched by the kernel, the mask with the
- closest matching generation is selected as the index into the mask array.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Bloom filters</title>
- <para>
- Bloom filters allow checking whether a given word is present in a
- dictionary. This allows connections to set up a mask for information it
- is interested in, and will be delivered signal messages that have a
- matching filter.
-
- For general information, see
- <ulink url="https://en.wikipedia.org/wiki/Bloom_filter">the Wikipedia
- article on bloom filters</ulink>.
- </para>
- <para>
- The size of the bloom filter is defined per bus when it is created, in
- <varname>kdbus_bloom_parameter.size</varname>. All bloom filters attached
- to signal messages on the bus must match this size, and all bloom filter
- matches uploaded by connections must also match the size, or a multiple
- thereof (see below).
-
- The calculation of the mask has to be done in userspace applications. The
- kernel just checks the bitmasks to decide whether or not to let the
- message pass. All bits in the mask must match the filter in and bit-wise
- <emphasis>AND</emphasis> logic, but the mask may have more bits set than
- the filter. Consequently, false positive matches are expected to happen,
- and programs must deal with that fact by checking the contents of the
- payload again at receive time.
- </para>
- <para>
- Masks are entities that are always passed to the kernel as part of a
- match (with an item of type <constant>KDBUS_ITEM_BLOOM_MASK</constant>),
- and filters can be attached to signals, with an item of type
- <constant>KDBUS_ITEM_BLOOM_FILTER</constant>. For a filter to match, all
- its bits have to be set in the match mask as well.
- </para>
- <para>
- For example, consider a bus that has a bloom size of 8 bytes, and the
- following mask/filter combinations:
- </para>
- <programlisting><![CDATA[
- filter 0x0101010101010101
- mask 0x0101010101010101
- -> matches
-
- filter 0x0303030303030303
- mask 0x0101010101010101
- -> doesn't match
-
- filter 0x0101010101010101
- mask 0x0303030303030303
- -> matches
- ]]></programlisting>
-
- <para>
- Hence, in order to catch all messages, a mask filled with
- <constant>0xff</constant> bytes can be installed as a wildcard match rule.
- </para>
-
- <refsect2>
- <title>Generations</title>
-
- <para>
- Uploaded matches may contain multiple masks, which have are as large as
- the bloom size defined by the bus. Each block of a mask is called a
- <emphasis>generation</emphasis>, starting at index 0.
-
- At match time, when a signal is about to be delivered, a bloom mask
- generation is passed, which denotes which of the bloom masks the filter
- should be matched against. This allows programs to provide backward
- compatible masks at upload time, while older clients can still match
- against older versions of filters.
- </para>
- </refsect2>
- </refsect1>
-
- <refsect1>
- <title>Matches for kernel notifications</title>
- <para>
- To receive kernel generated notifications (see
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>),
- a connection must install match rules that are different from
- the bloom filter matches described in the section above. They can be
- filtered by the connection ID that caused the notification to be sent, by
- one of the names it currently owns, or by the type of the notification
- (ID/name add/remove/change).
- </para>
- </refsect1>
-
- <refsect1>
- <title>Adding a match</title>
- <para>
- To add a match, the <constant>KDBUS_CMD_MATCH_ADD</constant> ioctl is
- used, which takes a struct of the struct described below.
-
- Note that each of the items attached to this command will internally
- create one match <emphasis>rule</emphasis>, and the collection of them,
- which is submitted as one block via the ioctl, is called a
- <emphasis>match</emphasis>. To allow a message to pass, all rules of a
- match have to be satisfied. Hence, adding more items to the command will
- only narrow the possibility of a match to effectively let the message
- pass, and will decrease the chance that the connection's process will be
- woken up needlessly.
-
- Multiple matches can be installed per connection. As long as one of it has
- a set of rules which allows the message to pass, this one will be
- decisive.
- </para>
-
- <programlisting>
-struct kdbus_cmd_match {
- __u64 size;
- __u64 flags;
- __u64 return_flags;
- __u64 cookie;
- 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 behavior of the ioctl.</para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_MATCH_REPLACE</constant></term>
- <listitem>
- <para>Make the endpoint file group-accessible</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>cookie</varname></term>
- <listitem><para>
- A cookie which identifies the match, so it can be referred to when
- removing it.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items to define the actual rules of the matches. The following item
- types are expected. Each item will create one new match rule.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
- <listitem>
- <para>
- An item that carries the bloom filter mask to match against
- in its data field. The payload size must match the bloom
- filter size that was specified when the bus was created.
- See the section below for more information on bloom filters.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME</constant></term>
- <listitem>
- <para>
- When used as part of kernel notifications, this item specifies
- a name that is acquired, lost or that changed its owner (see
- below). When used as part of a match for user-generated signal
- messages, it specifies a name that the sending connection must
- own at the time of sending the signal.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ID</constant></term>
- <listitem>
- <para>
- Specify a sender connection's ID that will match this rule.
- For kernel notifications, this specifies the ID of a
- connection that was added to or removed from the bus.
- For used-generated signals, it specifies the ID of the
- connection that sent the signal message.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
- <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
- <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
- <listitem>
- <para>
- These items request delivery of kernel notifications that
- describe a name acquisition, loss, or change. The details
- are stored in the item's
- <varname>kdbus_notify_name_change</varname> member.
- All information specified must be matched in order to make
- the message pass. Use
- <constant>KDBUS_MATCH_ID_ANY</constant> to
- match against any unique connection ID.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
- <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
- <listitem>
- <para>
- These items request delivery of kernel notifications that are
- generated when a connection is created or terminated.
- <type>struct kdbus_notify_id_change</type> is used to
- store the actual match information. This item can be used to
- monitor one particular connection ID, or, when the ID field
- is set to <constant>KDBUS_MATCH_ID_ANY</constant>,
- all of them.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
- <listitem><para>
- With this item, programs can <emphasis>probe</emphasis> the
- kernel for known item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Refer to
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on message types.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Removing a match</title>
- <para>
- Matches can be removed with the
- <constant>KDBUS_CMD_MATCH_REMOVE</constant> ioctl, which takes
- <type>struct kdbus_cmd_match</type> as argument, but its fields
- usage slightly differs compared to that of
- <constant>KDBUS_CMD_MATCH_ADD</constant>.
- </para>
-
- <programlisting>
-struct kdbus_cmd_match {
- __u64 size;
- __u64 cookie;
- __u64 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>cookie</varname></term>
- <listitem><para>
- The cookie of the match, as it was passed when the match was added.
- All matches that have this cookie will be removed.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>flags</varname></term>
- <listitem><para>
- No flags are supported for this use case.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will fail with
- <errorcode>-1</errorcode>, <varname>errno</varname> is set to
- <constant>EPROTO</constant>, and the <varname>flags</varname> field
- is set to <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- No items are supported for this use case, but
- <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed nevertheless.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal flags or items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EDOM</constant></term>
- <listitem><para>
- Illegal bloom filter size.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMFILE</constant></term>
- <listitem><para>
- Too many matches for this connection.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal flags.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EBADSLT</constant></term>
- <listitem><para>
- A match entry with the given cookie could not be found.
- </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.match</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.name</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>
- A kdbus message is used to exchange information between two connections
- on a bus, or to transport notifications from the kernel to one or many
- connections. This document describes the layout of messages, how payload
- is added to them and how they are sent and received.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Message layout</title>
-
- <para>The layout of a message is shown below.</para>
-
- <programlisting>
- +-------------------------------------------------------------------------+
- | Message |
- | +---------------------------------------------------------------------+ |
- | | Header | |
- | | size: overall message size, including the data records | |
- | | destination: connection ID of the receiver | |
- | | source: connection ID of the sender (set by kernel) | |
- | | payload_type: "DBusDBus" textual identifier stored as uint64_t | |
- | +---------------------------------------------------------------------+ |
- | +---------------------------------------------------------------------+ |
- | | Data Record | |
- | | size: overall record size (without padding) | |
- | | type: type of data | |
- | | data: reference to data (address or file descriptor) | |
- | +---------------------------------------------------------------------+ |
- | +---------------------------------------------------------------------+ |
- | | padding bytes to the next 8 byte alignment | |
- | +---------------------------------------------------------------------+ |
- | +---------------------------------------------------------------------+ |
- | | Data Record | |
- | | size: overall record size (without padding) | |
- | | ... | |
- | +---------------------------------------------------------------------+ |
- | +---------------------------------------------------------------------+ |
- | | padding bytes to the next 8 byte alignment | |
- | +---------------------------------------------------------------------+ |
- | +---------------------------------------------------------------------+ |
- | | Data Record | |
- | | size: overall record size | |
- | | ... | |
- | +---------------------------------------------------------------------+ |
- | ... further data records ... |
- +-------------------------------------------------------------------------+
- </programlisting>
- </refsect1>
-
- <refsect1>
- <title>Message payload</title>
-
- <para>
- When connecting to the bus, receivers request a memory pool of a given
- size, large enough to carry all backlog of data enqueued for the
- connection. The pool is internally backed by a shared memory file which
- can be <function>mmap()</function>ed by the receiver. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information.
- </para>
-
- <para>
- Message payload must be described in items attached to a message when
- it is sent. A receiver can access the payload by looking at the items
- that are attached to a message in its pool. The following items are used.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
- <listitem>
- <para>
- This item references a piece of memory on the sender side which is
- directly copied into the receiver's pool. This way, two peers can
- exchange data by effectively doing a single-copy from one process
- to another; the kernel will not buffer the data anywhere else.
- This item is never found in a message received by a connection.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
- <listitem>
- <para>
- This item is attached to messages on the receiving side and points
- to a memory area inside the receiver's pool. The
- <varname>offset</varname> variable in the item denotes the memory
- location relative to the message itself.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
- <listitem>
- <para>
- Messages can reference <emphasis>memfd</emphasis> files which
- contain the data. memfd files are tmpfs-backed files that allow
- sealing of the content of the file, which prevents all writable
- access to the file content.
- </para>
- <para>
- Only memfds that have
- <constant>(F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL)
- </constant>
- set are accepted as payload data, which enforces reliable passing of
- data. The receiver can assume that neither the sender nor anyone
- else can alter the content after the message is sent. If those
- seals are not set on the memfd, the ioctl will fail with
- <errorcode>-1</errorcode>, and <varname>errno</varname> will be
- set to <constant>ETXTBUSY</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_FDS</constant></term>
- <listitem>
- <para>
- Messages can transport regular file descriptors via
- <constant>KDBUS_ITEM_FDS</constant>. This item carries an array
- of <type>int</type> values in <varname>item.fd</varname>. The
- maximum number of file descriptors in the item is
- <constant>253</constant>, and only one item of this type is
- accepted per message. All passed values must be valid file
- descriptors; the open count of each file descriptors is increased
- by installing it to the receiver's task. This item can only be
- used for directed messages, not for broadcasts, and only to
- remote peers that have opted-in for receiving file descriptors
- at connection time (<constant>KDBUS_HELLO_ACCEPT_FD</constant>).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The sender must not make any assumptions on the type in which data is
- received by the remote peer. The kernel is free to re-pack multiple
- <constant>KDBUS_ITEM_PAYLOAD_VEC</constant> and
- <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> payloads. For instance, the
- kernel may decide to merge multiple <constant>VECs</constant> into a
- single <constant>VEC</constant>, inline <constant>MEMFD</constant>
- payloads into memory, or merge all passed <constant>VECs</constant> into a
- single <constant>MEMFD</constant>. However, the kernel preserves the order
- of passed data. This means that the order of all <constant>VEC</constant>
- and <constant>MEMFD</constant> items is not changed in respect to each
- other. In other words: All passed <constant>VEC</constant> and
- <constant>MEMFD</constant> data payloads are treated as a single stream
- of data that may be received by the remote peer in a different set of
- chunks than it was sent as.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Sending messages</title>
-
- <para>
- Messages are passed to the kernel with the
- <constant>KDBUS_CMD_SEND</constant> ioctl. Depending on the destination
- address of the message, the kernel delivers the message to the specific
- destination connection, or to some subset of all connections on the same
- bus. Sending messages across buses is not possible. Messages are always
- queued in the memory pool of the destination connection (see above).
- </para>
-
- <para>
- The <constant>KDBUS_CMD_SEND</constant> ioctl uses a
- <type>struct kdbus_cmd_send</type> to describe the message
- transfer.
- </para>
- <programlisting>
-struct kdbus_cmd_send {
- __u64 size;
- __u64 flags;
- __u64 return_flags;
- __u64 msg_address;
- struct kdbus_msg_info reply;
- struct kdbus_item items[0];
-};
- </programlisting>
-
- <para>The fields in this struct are described below.</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>size</varname></term>
- <listitem><para>
- The overall size of the struct, including its items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>flags</varname></term>
- <listitem><para>Flags for message delivery</para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_SEND_SYNC_REPLY</constant></term>
- <listitem>
- <para>
- By default, all calls to kdbus are considered asynchronous,
- non-blocking. However, as there are many use cases that need
- to wait for a remote peer to answer a method call, there's a
- way to send a message and wait for a reply in a synchronous
- fashion. This is what the
- <constant>KDBUS_SEND_SYNC_REPLY</constant> controls. The
- <constant>KDBUS_CMD_SEND</constant> ioctl will block until the
- reply has arrived, the timeout limit is reached, in case the
- remote connection was shut down, or if interrupted by a signal
- before any reply; see
- <citerefentry>
- <refentrytitle>signal</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
-
- The offset of the reply message in the sender's pool is stored
- in in <varname>offset_reply</varname> when the ioctl has
- returned without error. Hence, there is no need for another
- <constant>KDBUS_CMD_RECV</constant> ioctl or anything else to
- receive the reply.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Request a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will fail with
- <errorcode>-1</errorcode>, <varname>errno</varname>
- is set to <constant>EPROTO</constant>.
- Once the ioctl returned, the <varname>flags</varname>
- field will have all bits set that the kernel recognizes as
- valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>msg_address</varname></term>
- <listitem><para>
- In this field, users have to provide a pointer to a message
- (<type>struct kdbus_msg</type>) to send. See below for a
- detailed description.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>reply</varname></term>
- <listitem><para>
- Only used for synchronous replies. See description of
- <type>struct kdbus_cmd_recv</type> for more details.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- The following items are currently recognized.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
- <listitem>
- <para>
- When this optional item is passed in, and the call is
- executed as SYNC call, the passed in file descriptor can be
- used as alternative cancellation point. The kernel will call
- <citerefentry>
- <refentrytitle>poll</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- on this file descriptor, and once it reports any incoming
- bytes, the blocking send operation will be canceled; the
- blocking, synchronous ioctl call will return
- <errorcode>-1</errorcode>, and <varname>errno</varname> will
- be set to <errorname>ECANCELED</errorname>.
- Any type of file descriptor on which
- <citerefentry>
- <refentrytitle>poll</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- can be called on can be used as payload to this item; for
- example, an eventfd can be used for this purpose, see
- <citerefentry>
- <refentrytitle>eventfd</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>.
- For asynchronous message sending, this item is allowed but
- ignored.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The fields in this struct are described below.
- The message referenced the <varname>msg_address</varname> above has
- the following layout.
- </para>
-
- <programlisting>
-struct kdbus_msg {
- __u64 size;
- __u64 flags;
- __s64 priority;
- __u64 dst_id;
- __u64 src_id;
- __u64 payload_type;
- __u64 cookie;
- __u64 timeout_ns;
- __u64 cookie_reply;
- struct kdbus_item items[0];
-};
- </programlisting>
-
- <para>The fields in this struct are described below.</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>size</varname></term>
- <listitem><para>
- The overall size of the struct, including its items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>flags</varname></term>
- <listitem><para>Flags to describe message details.</para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_MSG_EXPECT_REPLY</constant></term>
- <listitem>
- <para>
- Expect a reply to this message from the remote peer. With
- this bit set, the timeout_ns field must be set to a non-zero
- number of nanoseconds in which the receiving peer is expected
- to reply. If such a reply is not received in time, the sender
- will be notified with a timeout message (see below). The
- value must be an absolute value, in nanoseconds and based on
- <constant>CLOCK_MONOTONIC</constant>.
- </para><para>
- For a message to be accepted as reply, it must be a direct
- message to the original sender (not a broadcast and not a
- signal message), and its
- <varname>kdbus_msg.reply_cookie</varname> must match the
- previous message's <varname>kdbus_msg.cookie</varname>.
- </para><para>
- Expected replies also temporarily open the policy of the
- sending connection, so the other peer is allowed to respond
- within the given time window.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_MSG_NO_AUTO_START</constant></term>
- <listitem>
- <para>
- By default, when a message is sent to an activator
- connection, the activator is notified and will start an
- implementer. This flag inhibits that behavior. With this bit
- set, and the remote being an activator, the ioctl will fail
- with <varname>errno</varname> set to
- <constant>EADDRNOTAVAIL</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>priority</varname></term>
- <listitem><para>
- The priority of this message. Receiving messages (see below) may
- optionally be constrained to messages of a minimal priority. This
- allows for use cases where timing critical data is interleaved with
- control data on the same connection. If unused, the priority field
- should be set to <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>dst_id</varname></term>
- <listitem><para>
- The numeric ID of the destination connection, or
- <constant>KDBUS_DST_ID_BROADCAST</constant>
- (~0ULL) to address every peer on the bus, or
- <constant>KDBUS_DST_ID_NAME</constant> (0) to look
- it up dynamically from the bus' name registry.
- In the latter case, an item of type
- <constant>KDBUS_ITEM_DST_NAME</constant> is mandatory.
- Also see
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- .
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>src_id</varname></term>
- <listitem><para>
- Upon return of the ioctl, this member will contain the sending
- connection's numerical ID. Should be 0 at send time.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>payload_type</varname></term>
- <listitem><para>
- Type of the payload in the actual data records. Currently, only
- <constant>KDBUS_PAYLOAD_DBUS</constant> is accepted as input value
- of this field. When receiving messages that are generated by the
- kernel (notifications), this field will contain
- <constant>KDBUS_PAYLOAD_KERNEL</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>cookie</varname></term>
- <listitem><para>
- Cookie of this message, for later recognition. Also, when replying
- to a message (see above), the <varname>cookie_reply</varname>
- field must match this value.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>timeout_ns</varname></term>
- <listitem><para>
- If the message sent requires a reply from the remote peer (see above),
- this field contains the timeout in absolute nanoseconds based on
- <constant>CLOCK_MONOTONIC</constant>. Also see
- <citerefentry>
- <refentrytitle>clock_gettime</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>cookie_reply</varname></term>
- <listitem><para>
- If the message sent is a reply to another message, this field must
- match the cookie of the formerly received message.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- A dynamically sized list of items to contain additional information.
- The following items are expected/valid:
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
- <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
- <term><constant>KDBUS_ITEM_FDS</constant></term>
- <listitem>
- <para>
- Actual data records containing the payload. See section
- "Passing of Payload Data".
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
- <listitem>
- <para>
- Bloom filter for matches (see below).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
- <listitem>
- <para>
- Well-known name to send this message to. Required if
- <varname>dst_id</varname> is set to
- <constant>KDBUS_DST_ID_NAME</constant>.
- If a connection holding the given name can't be found,
- the ioctl will fail with <varname>errno</varname> set to
- <constant>ESRCH</constant> is returned.
- </para>
- <para>
- For messages to a unique name (ID), this item is optional. If
- present, the kernel will make sure the name owner matches the
- given unique name. This allows programs to tie the message
- sending to the condition that a name is currently owned by a
- certain unique name.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The message will be augmented by the requested metadata items when
- queued into the receiver's pool. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on metadata.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Receiving messages</title>
-
- <para>
- Messages are received by the client with the
- <constant>KDBUS_CMD_RECV</constant> ioctl. The endpoint file of the bus
- supports <function>poll()/epoll()/select()</function>; when new messages
- are available on the connection's file descriptor,
- <constant>POLLIN</constant> is reported. For compatibility reasons,
- <constant>POLLOUT</constant> is always reported as well. Note, however,
- that the latter does not guarantee that a message can in fact be sent, as
- this depends on how many pending messages the receiver has in its pool.
- </para>
-
- <para>
- With the <constant>KDBUS_CMD_RECV</constant> ioctl, a
- <type>struct kdbus_cmd_recv</type> is used.
- </para>
-
- <programlisting>
-struct kdbus_cmd_recv {
- __u64 size;
- __u64 flags;
- __u64 return_flags;
- __s64 priority;
- __u64 dropped_msgs;
- struct kdbus_msg_info msg;
- struct kdbus_item items[0];
-};
- </programlisting>
-
- <para>The fields in this struct are described below.</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>size</varname></term>
- <listitem><para>
- The overall size of the struct, including its items.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>flags</varname></term>
- <listitem><para>Flags to control the receive command.</para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_RECV_PEEK</constant></term>
- <listitem>
- <para>
- Just return the location of the next message. Do not install
- file descriptors or anything else. This is usually used to
- determine the sender of the next queued message.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_RECV_DROP</constant></term>
- <listitem>
- <para>
- Drop the next message without doing anything else with it,
- and free the pool slice. This a short-cut for
- <constant>KDBUS_RECV_PEEK</constant> and
- <constant>KDBUS_CMD_FREE</constant>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_RECV_USE_PRIORITY</constant></term>
- <listitem>
- <para>
- Dequeue the messages ordered by their priority, and filtering
- them with the priority field (see below).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Request a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will fail with
- <errorcode>-1</errorcode>, <varname>errno</varname>
- is set to <constant>EPROTO</constant>.
- Once the ioctl returned, the <varname>flags</varname>
- field will have all bits set that the kernel recognizes as
- valid for this command.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. If the <varname>dropped_msgs</varname>
- field is non-zero, <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant>
- is set. If a file descriptor could not be installed, the
- <constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant> flag is set.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>priority</varname></term>
- <listitem><para>
- With <constant>KDBUS_RECV_USE_PRIORITY</constant> set in
- <varname>flags</varname>, messages will be dequeued ordered by their
- priority, starting with the highest value. Also, messages will be
- filtered by the value given in this field, so the returned message
- will at least have the requested priority. If no such message is
- waiting in the queue, the ioctl will fail, and
- <varname>errno</varname> will be set to <constant>EAGAIN</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>dropped_msgs</varname></term>
- <listitem><para>
- Whenever a message with <constant>KDBUS_MSG_SIGNAL</constant> is sent
- but cannot be queued on a peer (e.g., as it contains FDs but the peer
- does not support FDs, or there is no space left in the peer's pool..)
- the 'dropped_msgs' counter of the peer is incremented. On the next
- RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct
- and cleared on the peer. If it was non-zero, the
- <constant>KDBUS_RECV_RETURN_DROPPED_MSGS</constant> flag will be set
- in <varname>return_flags</varname>. Note that this will only happen
- if the ioctl succeeded or failed with <constant>EAGAIN</constant>. In
- other error cases, the 'dropped_msgs' field of the peer is left
- untouched.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>msg</varname></term>
- <listitem><para>
- Embedded struct containing information on the received message when
- this command succeeded (see below).
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem><para>
- Items to specify further details for the receive command.
- Currently unused, and all items will be rejected with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Both <type>struct kdbus_cmd_recv</type> and
- <type>struct kdbus_cmd_send</type> embed
- <type>struct kdbus_msg_info</type>.
- For the <constant>KDBUS_CMD_SEND</constant> ioctl, it is used to catch
- synchronous replies, if one was requested, and is unused otherwise.
- </para>
-
- <programlisting>
-struct kdbus_msg_info {
- __u64 offset;
- __u64 msg_size;
- __u64 return_flags;
-};
- </programlisting>
-
- <para>The fields in this struct are described below.</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>offset</varname></term>
- <listitem><para>
- Upon return of the ioctl, this field contains the offset in the
- receiver's memory pool. The memory must be freed with
- <constant>KDBUS_CMD_FREE</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further details.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>msg_size</varname></term>
- <listitem><para>
- Upon successful return of the ioctl, this field contains the size of
- the allocated slice at offset <varname>offset</varname>.
- It is the combination of the size of the stored
- <type>struct kdbus_msg</type> object plus all appended VECs.
- You can use it in combination with <varname>offset</varname> to map
- a single message, instead of mapping the entire pool. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for further details.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem>
- <para>
- Kernel-provided return flags. Currently, the following flags are
- defined.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_RECV_RETURN_INCOMPLETE_FDS</constant></term>
- <listitem>
- <para>
- The message contained memfds or file descriptors, and the
- kernel failed to install one or more of them at receive time.
- Most probably that happened because the maximum number of
- file descriptors for the receiver's task were exceeded.
- In such cases, the message is still delivered, so this is not
- a fatal condition. File descriptors numbers inside the
- <constant>KDBUS_ITEM_FDS</constant> item or memfd files
- referenced by <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant>
- items which could not be installed will be set to
- <constant>-1</constant>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Unless <constant>KDBUS_RECV_DROP</constant> was passed, the
- <varname>offset</varname> field contains the location of the new message
- inside the receiver's pool after the <constant>KDBUS_CMD_RECV</constant>
- ioctl was employed. The message is stored as <type>struct kdbus_msg</type>
- at this offset, and can be interpreted with the semantics described above.
- </para>
- <para>
- Also, if the connection allowed for file descriptor to be passed
- (<constant>KDBUS_HELLO_ACCEPT_FD</constant>), and if the message contained
- any, they will be installed into the receiving process when the
- <constant>KDBUS_CMD_RECV</constant> ioctl is called.
- <emphasis>memfds</emphasis> may always be part of the message payload.
- The receiving task is obliged to close all file descriptors appropriately
- once no longer needed. If <constant>KDBUS_RECV_PEEK</constant> is set, no
- file descriptors are installed. This allows for peeking at a message,
- looking at its metadata only and dropping it via
- <constant>KDBUS_RECV_DROP</constant>, without installing any of the file
- descriptors into the receiving process.
- </para>
- <para>
- The caller is obliged to call the <constant>KDBUS_CMD_FREE</constant>
- ioctl with the returned offset when the memory is no longer needed.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Notifications</title>
- <para>
- A kernel notification is a regular kdbus message with the following
- details.
- </para>
-
- <itemizedlist>
- <listitem><para>
- kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant>
- </para></listitem>
- <listitem><para>
- kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant>
- </para></listitem>
- <listitem><para>
- kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant>
- </para></listitem>
- <listitem><para>
- Has exactly one of the items attached that are described below.
- </para></listitem>
- <listitem><para>
- Always has a timestamp item (<constant>KDBUS_ITEM_TIMESTAMP</constant>)
- attached.
- </para></listitem>
- </itemizedlist>
-
- <para>
- The kernel will notify its users of the following events.
- </para>
-
- <itemizedlist>
- <listitem><para>
- When connection <emphasis>A</emphasis> is terminated while connection
- <emphasis>B</emphasis> is waiting for a reply from it, connection
- <emphasis>B</emphasis> is notified with a message with an item of
- type <constant>KDBUS_ITEM_REPLY_DEAD</constant>.
- </para></listitem>
-
- <listitem><para>
- When connection <emphasis>A</emphasis> does not receive a reply from
- connection <emphasis>B</emphasis> within the specified timeout window,
- connection <emphasis>A</emphasis> will receive a message with an
- item of type <constant>KDBUS_ITEM_REPLY_TIMEOUT</constant>.
- </para></listitem>
-
- <listitem><para>
- When an ordinary connection (not a monitor) is created on or removed
- from a bus, messages with an item of type
- <constant>KDBUS_ITEM_ID_ADD</constant> or
- <constant>KDBUS_ITEM_ID_REMOVE</constant>, respectively, are delivered
- to all bus members that match these messages through their match
- database. Eavesdroppers (monitor connections) do not cause such
- notifications to be sent. They are invisible on the bus.
- </para></listitem>
-
- <listitem><para>
- When a connection gains or loses ownership of a name, messages with an
- item of type <constant>KDBUS_ITEM_NAME_ADD</constant>,
- <constant>KDBUS_ITEM_NAME_REMOVE</constant> or
- <constant>KDBUS_ITEM_NAME_CHANGE</constant> are delivered to all bus
- members that match these messages through their match database.
- </para></listitem>
- </itemizedlist>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_SEND</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EOPNOTSUPP</constant></term>
- <listitem><para>
- The connection is not an ordinary connection, or the passed
- file descriptors in <constant>KDBUS_ITEM_FDS</constant> item are
- either kdbus handles or unix domain sockets. Both are currently
- unsupported.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- The submitted payload type is
- <constant>KDBUS_PAYLOAD_KERNEL</constant>,
- <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set without timeout
- or cookie values, <constant>KDBUS_SEND_SYNC_REPLY</constant> was
- set without <constant>KDBUS_MSG_EXPECT_REPLY</constant>, an invalid
- item was supplied, <constant>src_id</constant> was non-zero and was
- different from the current connection's ID, a supplied memfd had a
- size of 0, or a string was not properly null-terminated.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ENOTUNIQ</constant></term>
- <listitem><para>
- The supplied destination is
- <constant>KDBUS_DST_ID_BROADCAST</constant> and either
- file descriptors were passed, or
- <constant>KDBUS_MSG_EXPECT_REPLY</constant> was set,
- or a timeout was given.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>E2BIG</constant></term>
- <listitem><para>
- Too many items
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMSGSIZE</constant></term>
- <listitem><para>
- The size of the message header and items or the payload vector
- is excessive.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EEXIST</constant></term>
- <listitem><para>
- Multiple <constant>KDBUS_ITEM_FDS</constant>,
- <constant>KDBUS_ITEM_BLOOM_FILTER</constant> or
- <constant>KDBUS_ITEM_DST_NAME</constant> items were supplied.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EBADF</constant></term>
- <listitem><para>
- The supplied <constant>KDBUS_ITEM_FDS</constant> or
- <constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant> items
- contained an illegal file descriptor.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMEDIUMTYPE</constant></term>
- <listitem><para>
- The supplied memfd is not a sealed kdbus memfd.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EMFILE</constant></term>
- <listitem><para>
- Too many file descriptors inside a
- <constant>KDBUS_ITEM_FDS</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EBADMSG</constant></term>
- <listitem><para>
- An item had illegal size, both a <constant>dst_id</constant> and a
- <constant>KDBUS_ITEM_DST_NAME</constant> was given, or both a name
- and a bloom filter was given.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ETXTBSY</constant></term>
- <listitem><para>
- The supplied kdbus memfd file cannot be sealed or the seal
- was removed, because it is shared with other processes or
- still mapped with
- <citerefentry>
- <refentrytitle>mmap</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ECOMM</constant></term>
- <listitem><para>
- A peer does not accept the file descriptors addressed to it.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EFAULT</constant></term>
- <listitem><para>
- The supplied bloom filter size was not 64-bit aligned, or supplied
- memory could not be accessed by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EDOM</constant></term>
- <listitem><para>
- The supplied bloom filter size did not match the bloom filter
- size of the bus.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EDESTADDRREQ</constant></term>
- <listitem><para>
- <constant>dst_id</constant> was set to
- <constant>KDBUS_DST_ID_NAME</constant>, but no
- <constant>KDBUS_ITEM_DST_NAME</constant> was attached.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ESRCH</constant></term>
- <listitem><para>
- The name to look up was not found in the name registry.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EADDRNOTAVAIL</constant></term>
- <listitem><para>
- <constant>KDBUS_MSG_NO_AUTO_START</constant> was given but the
- destination connection is an activator.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ENXIO</constant></term>
- <listitem><para>
- The passed numeric destination connection ID couldn't be found,
- or is not connected.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ECONNRESET</constant></term>
- <listitem><para>
- The destination connection is no longer active.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ETIMEDOUT</constant></term>
- <listitem><para>
- Timeout while synchronously waiting for a reply.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINTR</constant></term>
- <listitem><para>
- Interrupted system call while synchronously waiting for a reply.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EPIPE</constant></term>
- <listitem><para>
- When sending a message, a synchronous reply from the receiving
- connection was expected but the connection died before answering.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ENOBUFS</constant></term>
- <listitem><para>
- Too many pending messages on the receiver side.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EREMCHG</constant></term>
- <listitem><para>
- Both a well-known name and a unique name (ID) was given, but
- the name is not currently owned by that connection.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EXFULL</constant></term>
- <listitem><para>
- The memory pool of the receiver is full.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EREMOTEIO</constant></term>
- <listitem><para>
- While synchronously waiting for a reply, the remote peer
- failed with an I/O error.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_RECV</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EOPNOTSUPP</constant></term>
- <listitem><para>
- The connection is not an ordinary connection, or the passed
- file descriptors are either kdbus handles or unix domain
- sockets. Both are currently unsupported.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Invalid flags or offset.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EAGAIN</constant></term>
- <listitem><para>
- No message found in the queue
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- </refsect1>
-
- <refsect1>
- <title>See Also</title>
- <simplelist type="inline">
- <member>
- <citerefentry>
- <refentrytitle>kdbus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.fs</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>clock_gettime</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>ioctl</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>poll</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>select</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>epoll</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>eventfd</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>memfd_create</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- </simplelist>
- </refsect1>
-</refentry>
+++ /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.name">
-
- <refentryinfo>
- <title>kdbus.name</title>
- <productname>kdbus.name</productname>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>kdbus.name</refname>
- <refpurpose>kdbus.name</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
- <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
- requested with <constant>KDBUS_CMD_NAME_LIST</constant>.
- </para>
-
- <para>
- All of the below is subject to policy rules for <emphasis>SEE</emphasis>
- and <emphasis>OWN</emphasis> 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 in order to be considered
- valid.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- The name has two or more elements separated by a
- '<literal>.</literal>' (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
- <literal>[A-Z][a-z][0-9]_</literal> and must not begin with a
- digit.
- </para>
- </listitem>
- <listitem>
- <para>
- The name must contain at least one '<literal>.</literal>' (period)
- character (and thus at least two elements).
- </para>
- </listitem>
- <listitem>
- <para>
- The name must not begin with a '<literal>.</literal>' (period)
- character.
- </para>
- </listitem>
- <listitem>
- <para>
- The name must not exceed <constant>255</constant> characters in
- length.
- </para>
- </listitem>
- </itemizedlist>
- </refsect1>
-
- <refsect1>
- <title>Acquiring a name</title>
- <para>
- To acquire a name, a client uses the
- <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with
- <type>struct kdbus_cmd</type> as argument.
- </para>
-
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 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><constant>KDBUS_NAME_REPLACE_EXISTING</constant></term>
- <listitem>
- <para>
- Acquiring a name that is already present usually fails,
- unless this flag is set in the call, and
- <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> (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><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></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><constant>KDBUS_NAME_QUEUE</constant></term>
- <listitem>
- <para>
- A name that is already acquired by a connection can not be
- acquired again (unless the
- <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag was
- set during acquisition; see above).
- 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>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Request a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will fail with
- <errorcode>-1</errorcode>, and <varname>errno</varname>
- is set to <constant>EPROTO</constant>.
- Once the ioctl returned, the <varname>flags</varname>
- field will have all bits set that the kernel recognizes as
- valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem>
- <para>
- Flags returned by the kernel. Currently, the following may be
- returned by the kernel.
- </para>
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
- <listitem>
- <para>
- The name was not acquired yet, but the connection was
- placed in the queue of peers waiting for the name.
- This can only happen if <constant>KDBUS_NAME_QUEUE</constant>
- was set in the <varname>flags</varname> member (see above).
- The connection will receive a name owner change notification
- once the current owner has given up the name and its
- ownership was transferred.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items to submit the name. Currently, one item of type
- <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
- the contained string must be a valid bus name.
- <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
- valid item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for a detailed description of how this item is used.
- </para>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Releasing a name</title>
- <para>
- A connection may release a name explicitly with the
- <constant>KDBUS_CMD_NAME_RELEASE</constant> 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 <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl uses the same data
- structure as the acquisition call
- (<constant>KDBUS_CMD_NAME_ACQUIRE</constant>),
- but with slightly different field usage.
- </para>
-
- <programlisting>
-struct kdbus_cmd {
- __u64 size;
- __u64 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 the command. Currently unused.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
- and the <varname>flags</varname> field is set to
- <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items to submit the name. Currently, one item of type
- <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
- the contained string must be a valid bus name.
- <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
- valid item types. See
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for a detailed description of how this item is used.
- </para>
- <para>
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- </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 <constant>KDBUS_CMD_LIST</constant> ioctl, which
- takes a <type>struct kdbus_cmd_list</type> as argument.
- </para>
-
- <programlisting>
-struct kdbus_cmd_list {
- __u64 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><constant>KDBUS_LIST_UNIQUE</constant></term>
- <listitem>
- <para>
- List the unique (numeric) IDs of the connection, whether it
- owns a name or not.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_LIST_NAMES</constant></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><constant>KDBUS_LIST_ACTIVATORS</constant></term>
- <listitem>
- <para>
- List names that are owned by an activator.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_LIST_QUEUED</constant></term>
- <listitem>
- <para>
- List connections that are not yet owning a name but are
- waiting for it to become available.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Request a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will fail with
- <errorcode>-1</errorcode>, and <varname>errno</varname>
- is set to <constant>EPROTO</constant>.
- Once the ioctl returned, the <varname>flags</varname>
- field will have all bits set that the kernel recognizes as
- valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>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 <type>struct kdbus_list</type>
- that in turn contains an array of type <type>struct kdbus_info</type>,
- The array-size in bytes is given as <varname>list_size</varname>.
- The fields inside <type>struct kdbus_info</type> is described next.
- </para>
-
- <programlisting>
-struct kdbus_info {
- __u64 size;
- __u64 id;
- __u64 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>id</varname></term>
- <listitem><para>
- The owning connection's unique ID.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>flags</varname></term>
- <listitem><para>
- The flags of the owning connection.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>items</varname></term>
- <listitem>
- <para>
- Items containing the actual name. Currently, one item of type
- <constant>KDBUS_ITEM_OWNED_NAME</constant> 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><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
- <listitem>
- <para>
- Other connections are allowed to take over this name from the
- connection that owns it.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_NAME_IN_QUEUE</constant></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><constant>KDBUS_NAME_ACTIVATOR</constant></term>
- <listitem>
- <para>
- An activator connection owns a name as a placeholder for an
- implementer, which is started on demand by programs 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
- <constant>KDBUS_NAME_REPLACE_EXISTING</constant>,
- 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 <constant>KDBUS_CMD_HELLO</constant>
- with <constant>KDBUS_HELLO_ACTIVATOR</constant> set in
- <varname>kdbus_cmd_hello.conn_flags</varname>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
- <listitem>
- <para>
- Requests a set of valid flags for this ioctl. When this bit is
- set, no action is taken; the ioctl will return
- <errorcode>0</errorcode>, and the <varname>flags</varname>
- field will have all bits set that are valid for this command.
- The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
- cleared by the operation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The returned buffer must be freed with the
- <constant>KDBUS_CMD_FREE</constant> 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 mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_NAME_ACQUIRE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Illegal command flags, illegal name provided, or an activator
- tried to acquire a second name.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EPERM</constant></term>
- <listitem><para>
- Policy prohibited name ownership.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EALREADY</constant></term>
- <listitem><para>
- Connection already owns that name.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EEXIST</constant></term>
- <listitem><para>
- The name already exists and can not be taken over.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>E2BIG</constant></term>
- <listitem><para>
- The maximum number of well-known names per connection is exhausted.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_NAME_RELEASE</constant>
- may fail with the following errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Invalid command flags, or invalid name provided.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ESRCH</constant></term>
- <listitem><para>
- Name is not found in the registry.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EADDRINUSE</constant></term>
- <listitem><para>
- Name is owned by a different connection and can't be released.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_LIST</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Invalid command flags
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>ENOBUFS</constant></term>
- <listitem><para>
- No available memory in the connection's pool.
- </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.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>kdbus.policy</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.policy">
-
- <refentryinfo>
- <title>kdbus.policy</title>
- <productname>kdbus.policy</productname>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>kdbus.policy</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>kdbus.policy</refname>
- <refpurpose>kdbus policy</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Description</title>
-
- <para>
- A kdbus policy restricts the possibilities of connections to own, see and
- talk to well-known names. A policy can be associated with a bus (through a
- policy holder connection) or a custom endpoint. kdbus stores its policy
- information in a database that can be accessed through the following
- ioctl commands:
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_CMD_HELLO</constant></term>
- <listitem><para>
- When creating, or updating, a policy holder connection. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
- <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
- <listitem><para>
- When creating, or updating, a bus custom endpoint. See
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- In all cases, the name and policy access information is stored in items
- of type <constant>KDBUS_ITEM_NAME</constant> and
- <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
- following rules apply.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
- by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
- </para>
- </listitem>
-
- <listitem>
- <para>
- An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
- by an arbitrary number of
- <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
- </para>
- </listitem>
-
- <listitem>
- <para>
- An arbitrary number of groups of names and access levels can be given.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
- comply to the rules of valid kdbus.name. See
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information.
-
- The payload of an item of type
- <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
- struct. For more information on the layout of items, please refer to
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para>
-
- <programlisting>
-struct kdbus_policy_access {
- __u64 type;
- __u64 access;
- __u64 id;
-};
- </programlisting>
-
- <para>The fields in this struct are described below.</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>type</varname></term>
- <listitem>
- <para>
- One of the following.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
- <listitem><para>
- Grant access to a user with the UID stored in the
- <varname>id</varname> field.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
- <listitem><para>
- Grant access to a user with the GID stored in the
- <varname>id</varname> field.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
- <listitem><para>
- Grant access to everyone. The <varname>id</varname> field
- is ignored.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>access</varname></term>
- <listitem>
- <para>
- The access to grant. One of the following.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_POLICY_SEE</constant></term>
- <listitem><para>
- Allow the name to be seen.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_POLICY_TALK</constant></term>
- <listitem><para>
- Allow the name to be talked to.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_POLICY_OWN</constant></term>
- <listitem><para>
- Allow the name to be owned.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>id</varname></term>
- <listitem><para>
- For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
- For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
- </para></listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- All endpoints of buses have an empty policy database by default.
- Therefore, unless policy rules are added, all operations will also be
- denied by default. Also see
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Wildcard names</title>
- <para>
- Policy holder connections may upload names that contain the wildcard
- suffix (<literal>".*"</literal>). Such a policy entry is effective for
- every well-known name that extends the provided name by exactly one more
- level.
-
- For example, the name <literal>foo.bar.*</literal> matches both
- <literal>"foo.bar.baz"</literal> and
- <literal>"foo.bar.bazbaz"</literal> are, but not
- <literal>"foo.bar.baz.baz"</literal>.
-
- This allows connections to take control over multiple names that the
- policy holder doesn't need to know about when uploading the policy.
-
- Such wildcard entries are not allowed for custom endpoints.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Privileged connections</title>
- <para>
- The policy database is overruled when action is taken by a privileged
- connection. Please refer to
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information on what makes a connection privileged.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
- <para>
- For instance, a set of policy rules may look like this:
- </para>
-
- <programlisting>
-KDBUS_ITEM_NAME: str='org.foo.bar'
-KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
-KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
-KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE
-
-KDBUS_ITEM_NAME: str='org.blah.baz'
-KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
-KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
- </programlisting>
-
- <para>
- That means that 'org.foo.bar' may only be owned by UID 1000, but every
- user on the bus is allowed to see the name. However, only UID 1001 may
- actually send a message to the connection and receive a reply from it.
-
- The second rule allows 'org.blah.baz' to be owned by UID 0 only, but
- every user may talk to it.
- </para>
- </refsect1>
-
- <refsect1>
- <title>TALK access and multiple well-known names per connection</title>
- <para>
- Note that TALK access is checked against all names of a connection. For
- example, if a connection owns both <constant>'org.foo.bar'</constant> and
- <constant>'org.blah.baz'</constant>, and the policy database allows
- <constant>'org.blah.baz'</constant> to be talked to by WORLD, then this
- permission is also granted to <constant>'org.foo.bar'</constant>. That
- might sound illogical, but after all, we allow messages to be directed to
- either the ID or a well-known name, and policy is applied to the
- connection, not the name. In other words, the effective TALK policy for a
- connection is the most permissive of all names the connection owns.
-
- For broadcast messages, the receiver needs TALK permissions to the sender
- to receive the broadcast.
- </para>
- <para>
- Both the endpoint and the bus policy databases are consulted to allow
- name registry listing, owning a well-known name and message delivery.
- If either one fails, the operation is failed with
- <varname>errno</varname> set to <constant>EPERM</constant>.
-
- For best practices, connections that own names with a restricted TALK
- access should not install matches. This avoids cases where the sent
- message may pass the bloom filter due to false-positives and may also
- satisfy the policy rules.
-
- Also see
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Implicit policies</title>
- <para>
- Depending on the type of the endpoint, a set of implicit rules that
- override installed policies might be enforced.
-
- On default endpoints, the following set is enforced and checked before
- any user-supplied policy is checked.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Privileged connections always override any installed policy. Those
- connections could easily install their own policies, so there is no
- reason to enforce installed policies.
- </para>
- </listitem>
- <listitem>
- <para>
- Connections can always talk to connections of the same user. This
- includes broadcast messages.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Custom endpoints have stricter policies. The following rules apply:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Policy rules are always enforced, even if the connection is a
- privileged connection.
- </para>
- </listitem>
- <listitem>
- <para>
- Policy rules are always enforced for <constant>TALK</constant> access,
- even if both ends are running under the same user. This includes
- broadcast messages.
- </para>
- </listitem>
- <listitem>
- <para>
- To restrict the set of names that can be seen, endpoint policies can
- install <constant>SEE</constant> policies.
- </para>
- </listitem>
- </itemizedlist>
- </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.name</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.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>pool_size</varname> member of <type>struct kdbus_cmd_hello</type>
- when <constant>KDBUS_CMD_HELLO</constant> is employed. Internally, the
- pool is segmented into <emphasis>slices</emphasis>, each referenced by its
- <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
- See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more information about <constant>KDBUS_CMD_HELLO</constant>.
- </para>
-
- <para>
- The pool is written to by the kernel when one of the following
- <emphasis>ioctls</emphasis> is issued:
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_CMD_HELLO</constant></term>
- <listitem><para>
- ... to receive details about the bus the connection was made to
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>KDBUS_CMD_RECV</constant></term>
- <listitem><para>
- ... to receive a message
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>KDBUS_CMD_LIST</constant></term>
- <listitem><para>
- ... to dump the name registry
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term><constant>KDBUS_CMD_CONN_INFO</constant></term>
- <listitem><para>
- ... to retrieve information on a connection
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- </para>
- <para>
- The <varname>offset</varname> fields returned by either one of the
- aforementioned ioctls describe offsets inside the pool. In order to make
- the slice available for subsequent calls,
- <constant>KDBUS_CMD_FREE</constant> has to be called on that offset
- (see below). Otherwise, the pool will fill up, and the connection won't
- be able to receive any more information through its pool.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Pool slice allocation</title>
- <para>
- Pool slices are allocated by the kernel in order to report information
- back to a task, such as messages, returned name list etc.
- Allocation of pool slices cannot be initiated by userspace. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- and
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for examples of commands that use the <emphasis>pool</emphasis> to
- return data.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Accessing the pool memory</title>
- <para>
- Memory in the pool is read-only for userspace and may only be written
- to by the kernel. To read from the pool memory, the caller is expected to
- <citerefentry>
- <refentrytitle>mmap</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- the buffer into its task, like this:
- </para>
- <programlisting>
-uint8_t *buf = mmap(NULL, size, PROT_READ, MAP_SHARED, conn_fd, 0);
- </programlisting>
-
- <para>
- In order to map the entire pool, the <varname>size</varname> parameter in
- the example above should be set to the value of the
- <varname>pool_size</varname> member of
- <type>struct kdbus_cmd_hello</type> when
- <constant>KDBUS_CMD_HELLO</constant> was employed to create the
- connection (see above).
- </para>
-
- <para>
- The <emphasis>file descriptor</emphasis> used to map the memory must be
- the one that was used to create the <emphasis>connection</emphasis>.
- In other words, the one that was used to call
- <constant>KDBUS_CMD_HELLO</constant>. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para>
-
- <para>
- Alternatively, instead of mapping the entire pool buffer, only parts
- of it can be mapped. Every kdbus command that returns an
- <emphasis>offset</emphasis> (see above) also reports a
- <emphasis>size</emphasis> along with it, so programs can be written
- in a way that it only maps portions of the pool to access a specific
- <emphasis>slice</emphasis>.
- </para>
-
- <para>
- When access to the pool memory is no longer needed, programs should
- call <function>munmap()</function> on the pointer returned by
- <function>mmap()</function>.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Freeing pool slices</title>
- <para>
- The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice
- inside the pool, describing an offset that was returned in an
- <varname>offset</varname> field of another ioctl struct.
- The <constant>KDBUS_CMD_FREE</constant> command takes a
- <type>struct kdbus_cmd_free</type> as argument.
- </para>
-
-<programlisting>
-struct kdbus_cmd_free {
- __u64 size;
- __u64 flags;
- __u64 return_flags;
- __u64 offset;
- 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>
- Currently unused.
- <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
- valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
- and the <varname>flags</varname> field is set to
- <constant>0</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>return_flags</varname></term>
- <listitem><para>
- Flags returned by the kernel. Currently unused and always set to
- <constant>0</constant> by the kernel.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>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>items</varname></term>
- <listitem><para>
- Items to specify further details for the receive command.
- Currently unused.
- Unrecognized items are rejected, and the ioctl will fail with
- <varname>errno</varname> set to <constant>EINVAL</constant>.
- All items except for
- <constant>KDBUS_ITEM_NEGOTIATE</constant> (see
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- ) will be rejected.
- </para></listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
- <refsect1>
- <title>Return value</title>
- <para>
- On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
- on error, <errorcode>-1</errorcode> is returned, and
- <varname>errno</varname> is set to indicate the error.
- If the issued ioctl is illegal for the file descriptor used,
- <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
- </para>
-
- <refsect2>
- <title>
- <constant>KDBUS_CMD_FREE</constant> may fail with the following
- errors
- </title>
-
- <variablelist>
- <varlistentry>
- <term><constant>ENXIO</constant></term>
- <listitem><para>
- No pool slice found at given offset.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></term>
- <listitem><para>
- Invalid flags provided.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>EINVAL</constant></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
- <constant>KDBUS_RECV_PEEK</constant>.
- </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.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>mmap</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- </member>
- <member>
- <citerefentry>
- <refentrytitle>munmap</refentrytitle>
- <manvolnum>2</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>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>kdbus</refentrytitle>
- <manvolnum>7</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>kdbus</refname>
- <refpurpose>Kernel Message Bus</refpurpose>
- </refnamediv>
-
- <refsect1>
- <title>Synopsis</title>
- <para>
- kdbus is an inter-process communication bus system controlled by the
- kernel. It provides user-space with an API to create buses and 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>
- This set of man-pages gives a comprehensive overview of the kernel-level
- API, with all ioctl commands, associated structs and bit masks. However,
- most people will not use this API level directly, but rather let one of
- the high-level abstraction libraries help them integrate D-Bus
- functionality into their applications.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Description</title>
- <para>
- kdbus provides a pseudo filesystem called <emphasis>kdbusfs</emphasis>,
- which is usually mounted on <filename>/sys/fs/kdbus</filename>. Bus
- primitives can be accessed as files and sub-directories 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 new mount-namespace. kdbus calls these
- mount instances domains and each bus belongs to exactly one domain.
- </para>
-
- <para>
- kdbus was designed as a 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, its payload format, its
- marshaling, and its 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>Domain</title>
- <para>
- A domain is a <emphasis>kdbusfs</emphasis> mount-point containing all
- the bus primitives. Each domain is independent, and separate domains
- do not affect each other.
- </para>
- </refsect2>
-
- <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, 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. 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, an application must mmap() it into its address space. 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. An analogy of connection ID and well-known name is an
- IP address and a DNS name associated with that address. See
- <citerefentry>
- <refentrytitle>kdbus.name</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 time stamps, 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
- <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
- <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 white-lists the message's filter. Senders
- of signal messages can use either a single connection ID as receiver,
- or the special connection ID
- <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
- all connections of a bus, following the logic described above. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </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
- <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>Bus Layout</title>
-
- <para>
- A <emphasis>bus</emphasis> 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
- <emphasis>connection</emphasis>, you have to open one of the
- <emphasis>endpoints</emphasis> 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>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>Metadata</title>
-
- <refsect2>
- <title>When metadata is collected</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 time stamps.
- </para>
- <para>
- Metadata is collected at the following times.
- </para>
-
- <itemizedlist>
- <listitem><para>
- When a bus is created (<constant>KDBUS_CMD_MAKE</constant>),
- information about the calling task is collected. This data is returned
- by the kernel via the <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant>
- call.
- </para></listitem>
-
- <listitem>
- <para>
- When a connection is created (<constant>KDBUS_CMD_HELLO</constant>),
- information about the calling task is collected. Alternatively, a
- privileged connection may provide 'faked' information about
- credentials, PIDs and security labels which will be stored instead.
- This data is returned by the kernel as information on a connection
- (<constant>KDBUS_CMD_CONN_INFO</constant>). Only metadata that a
- connection allowed to be sent (by setting its bit in
- <varname>attach_flags_send</varname>) will be exported in this way.
- </para>
- </listitem>
-
- <listitem>
- <para>
- When a message is sent (<constant>KDBUS_CMD_SEND</constant>),
- 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. Note that only metadata that was requested
- by the receiving connection will be collected and attached to
- messages.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Which metadata items are actually delivered depends on the following
- sets and masks:
- </para>
-
- <itemizedlist>
- <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>
- <listitem>
- <para>
- [1] The creds attached to messages are determined as
- <constant>a & b & c</constant>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>),
- and <constant>~b & d != 0</constant>, the call will fail with,
- <errorcode>-1</errorcode>, and <varname>errno</varname> is set to
- <constant>ECONNREFUSED</constant>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- [3] When querying creds of a bus peer, the creds returned are
- <constant>a & b & f</constant>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- [4] When querying creds of a bus owner, the creds returned are
- <constant>a & e & g</constant>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Hence, programs 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>
-
- <refsect2>
- <title>Benefits and heads-up</title>
- <para>
- Attaching metadata to messages has two major benefits.
-
- <itemizedlist>
- <listitem>
- <para>
- Metadata attached to messages is gathered at the moment when the
- other side calls <constant>KDBUS_CMD_SEND</constant>, or,
- respectively, then the kernel notification is generated. There is
- no need for the receiving peer to retrieve information about the
- task in a second step. This closes a race gap that would otherwise
- be inherent.
- </para>
- </listitem>
- <listitem>
- <para>
- As metadata is delivered along with messages in the same data
- blob, no extra calls to kernel functions etc. are needed to gather
- them.
- </para>
- </listitem>
- </itemizedlist>
-
- Note, however, that collecting metadata does come at a price for
- performance, so developers should carefully assess which metadata to
- really opt-in for. For best practice, data that is not needed as part
- of a message should not be requested by the connection in the first
- place (see <varname>attach_flags_recv</varname> in
- <constant>KDBUS_CMD_HELLO</constant>).
- </para>
- </refsect2>
-
- <refsect2>
- <title>Attach flags for metadata items</title>
- <para>
- To let the kernel know which metadata information to attach as items
- to the aforementioned commands, it uses a bitmask. In those, the
- following <emphasis>attach flags</emphasis> are currently supported.
- Both the the <varname>attach_flags_recv</varname> and
- <varname>attach_flags_send</varname> fields of
- <type>struct kdbus_cmd_hello</type>, as well as the payload of the
- <constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant> and
- <constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant> items follow this
- scheme.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_TIMESTAMP</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_CREDS</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_CREDS</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_PIDS</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_PIDS</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_AUXGROUPS</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_NAMES</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_OWNED_NAME</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_TID_COMM</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_TID_COMM</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_PID_COMM</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_PID_COMM</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_EXE</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_EXE</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_CMDLINE</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_CMDLINE</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_CGROUP</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_CGROUP</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_CAPS</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_CAPS</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_SECLABEL</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_SECLABEL</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_AUDIT</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_AUDIT</constant>.
- </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term>
- <listitem><para>
- Requests the attachment of an item of type
- <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>.
- </para></listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Please refer to
- <citerefentry>
- <refentrytitle>kdbus.item</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for detailed information about the layout and payload of items and
- what metadata should be used to.
- </para>
- </refsect2>
- </refsect1>
-
- <refsect1>
- <title>The ioctl interface</title>
-
- <para>
- As stated in the 'synopsis' section above, application developers are
- strongly encouraged to use kdbus through one of the high-level D-Bus
- abstraction libraries, rather than using the low-level API directly.
- </para>
-
- <para>
- kdbus on the kernel level exposes its functions exclusively through
- <citerefentry>
- <refentrytitle>ioctl</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>,
- employed on 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, along with the command structs
- they must be used with.
- </para>
-
- <informaltable frame="none">
- <tgroup cols="3" colsep="1">
- <thead>
- <row>
- <entry>ioctl signature</entry>
- <entry>command</entry>
- <entry>transported struct</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><constant>0x40189500</constant></entry>
- <entry><constant>KDBUS_CMD_BUS_MAKE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x40189510</constant></entry>
- <entry><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0xc0609580</constant></entry>
- <entry><constant>KDBUS_CMD_HELLO</constant></entry>
- <entry><type>struct kdbus_cmd_hello *</type></entry>
- </row><row>
- <entry><constant>0x40189582</constant></entry>
- <entry><constant>KDBUS_CMD_BYEBYE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x40389590</constant></entry>
- <entry><constant>KDBUS_CMD_SEND</constant></entry>
- <entry><type>struct kdbus_cmd_send *</type></entry>
- </row><row>
- <entry><constant>0x80409591</constant></entry>
- <entry><constant>KDBUS_CMD_RECV</constant></entry>
- <entry><type>struct kdbus_cmd_recv *</type></entry>
- </row><row>
- <entry><constant>0x40209583</constant></entry>
- <entry><constant>KDBUS_CMD_FREE</constant></entry>
- <entry><type>struct kdbus_cmd_free *</type></entry>
- </row><row>
- <entry><constant>0x401895a0</constant></entry>
- <entry><constant>KDBUS_CMD_NAME_ACQUIRE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x401895a1</constant></entry>
- <entry><constant>KDBUS_CMD_NAME_RELEASE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x80289586</constant></entry>
- <entry><constant>KDBUS_CMD_LIST</constant></entry>
- <entry><type>struct kdbus_cmd_list *</type></entry>
- </row><row>
- <entry><constant>0x80309584</constant></entry>
- <entry><constant>KDBUS_CMD_CONN_INFO</constant></entry>
- <entry><type>struct kdbus_cmd_info *</type></entry>
- </row><row>
- <entry><constant>0x40209551</constant></entry>
- <entry><constant>KDBUS_CMD_UPDATE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x80309585</constant></entry>
- <entry><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></entry>
- <entry><type>struct kdbus_cmd_info *</type></entry>
- </row><row>
- <entry><constant>0x40189511</constant></entry>
- <entry><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></entry>
- <entry><type>struct kdbus_cmd *</type></entry>
- </row><row>
- <entry><constant>0x402095b0</constant></entry>
- <entry><constant>KDBUS_CMD_MATCH_ADD</constant></entry>
- <entry><type>struct kdbus_cmd_match *</type></entry>
- </row><row>
- <entry><constant>0x402095b1</constant></entry>
- <entry><constant>KDBUS_CMD_MATCH_REMOVE</constant></entry>
- <entry><type>struct kdbus_cmd_match *</type></entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- Depending on the type of <emphasis>kdbusfs</emphasis> node that was
- opened and what ioctls have been executed on a file descriptor before,
- a different sub-set of ioctl commands is allowed.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- On a file descriptor resulting from opening a
- <emphasis>control node</emphasis>, only the
- <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl may be executed.
- </para>
- </listitem>
- <listitem>
- <para>
- On a file descriptor resulting from opening a
- <emphasis>bus endpoint node</emphasis>, only the
- <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> and
- <constant>KDBUS_CMD_HELLO</constant> ioctls may be executed.
- </para>
- </listitem>
- <listitem>
- <para>
- A file descriptor that was used to create a bus
- (via <constant>KDBUS_CMD_BUS_MAKE</constant>) is called a
- <emphasis>bus owner</emphasis> file descriptor. The bus will be
- active as long as the file descriptor is kept open.
- A bus owner file descriptor can not be used to
- employ any further ioctls. As soon as
- <citerefentry>
- <refentrytitle>close</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- is called on it, the bus will be shut down, along will all associated
- endpoints and connections. See
- <citerefentry>
- <refentrytitle>kdbus.bus</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para>
- </listitem>
- <listitem>
- <para>
- A file descriptor that was used to create an endpoint
- (via <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>) is called an
- <emphasis>endpoint owner</emphasis> file descriptor. The endpoint
- will be active as long as the file descriptor is kept open.
- An endpoint owner file descriptor can only be used
- to update details of an endpoint through the
- <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> ioctl. As soon as
- <citerefentry>
- <refentrytitle>close</refentrytitle>
- <manvolnum>2</manvolnum>
- </citerefentry>
- is called on it, the endpoint will be removed from the bus, and all
- connections that are connected to the bus through it are shut down.
- See
- <citerefentry>
- <refentrytitle>kdbus.endpoint</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>
- for more details.
- </para>
- </listitem>
- <listitem>
- <para>
- A file descriptor that was used to create a connection
- (via <constant>KDBUS_CMD_HELLO</constant>) is called a
- <emphasis>connection owner</emphasis> file descriptor. The connection
- will be active as long as the file descriptor is kept open.
- A connection owner file descriptor may be used to
- issue any of the following ioctls.
- </para>
-
- <itemizedlist>
- <listitem><para>
- <constant>KDBUS_CMD_UPDATE</constant> to tweak details of the
- connection. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_BYEBYE</constant> to shut down a connection
- without losing messages. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_FREE</constant> to free a slice of memory in
- the pool. See
- <citerefentry>
- <refentrytitle>kdbus.pool</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_CONN_INFO</constant> to retrieve information
- on other connections on the bus. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> to retrieve
- information on the bus creator. See
- <citerefentry>
- <refentrytitle>kdbus.connection</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_LIST</constant> to retrieve a list of
- currently active well-known names and unique IDs on the bus. See
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_SEND</constant> and
- <constant>KDBUS_CMD_RECV</constant> to send or receive a message.
- See
- <citerefentry>
- <refentrytitle>kdbus.message</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_NAME_ACQUIRE</constant> and
- <constant>KDBUS_CMD_NAME_RELEASE</constant> to acquire or release
- a well-known name on the bus. See
- <citerefentry>
- <refentrytitle>kdbus.name</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
-
- <listitem><para>
- <constant>KDBUS_CMD_MATCH_ADD</constant> and
- <constant>KDBUS_CMD_MATCH_REMOVE</constant> to add or remove
- a match for signal messages. See
- <citerefentry>
- <refentrytitle>kdbus.match</refentrytitle>
- <manvolnum>7</manvolnum>
- </citerefentry>.
- </para></listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
- <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>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.name</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>
%docs: scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc
$(Q)$(MAKE) $(build)=Documentation/DocBook $@
- $(Q)$(MAKE) $(build)=Documentation/kdbus $@
else # KBUILD_EXTMOD
projects / platform / kernel / linux-exynos.git / commitdiff