Google Git
Sign in
kernel / pub / scm / linux / kernel / git / pjw / tegra-pending / for-epmt / . / Documentation / kdbus / kdbus.connection.xml
blob: cefb419f10939c2345b4438b544b683c95a45508 [file] [log] [blame]
<?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. 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>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>