path: root/Documentation/kdbus/kdbus.connection.xml

<?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>