summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.connection.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kdbus/kdbus.connection.xml')
-rw-r--r--Documentation/kdbus/kdbus.connection.xml1244
1 files changed, 1244 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml
new file mode 100644
index 000000000..4bb5f30f3
--- /dev/null
+++ b/Documentation/kdbus/kdbus.connection.xml
@@ -0,0 +1,1244 @@
+<?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.&lt;ID&gt;"</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.
+ </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>attach_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>
+ 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>