path: root/Documentation/kdbus/kdbus.bus.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.bus">

  <refentryinfo>
    <title>kdbus.bus</title>
    <productname>kdbus.bus</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>kdbus.bus</refentrytitle>
    <manvolnum>7</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>kdbus.bus</refname>
    <refpurpose>kdbus bus</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>
      A bus is a resource that is shared between connections in order to
      transmit messages (see
      <citerefentry>
        <refentrytitle>kdbus.message</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>).
      Each bus is independent, and operations on the bus will not have any
      effect on other buses. A bus is a management entity that controls the
      addresses of its connections, their policies and message transactions
      performed via this bus.
    </para>
    <para>
      Each bus is bound to the mount instance it was created on. It has a
      custom name that is unique across all buses of a domain. In
      <citerefentry>
        <refentrytitle>kdbus.fs</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>
      a bus is presented as a directory. No operations can be performed on
      the bus itself; instead you need to perform the operations on an endpoint
      associated with the bus. Endpoints are accessible as files underneath the
      bus directory. A default endpoint called <constant>bus</constant> is
      provided on each bus.
    </para>
    <para>
      Bus names may be chosen freely except for one restriction: the name must
      be prefixed with the numeric effective UID of the creator and a dash. This
      is required to avoid namespace clashes between different users. When
      creating a bus, the name that is passed in must be properly formatted, or
      the kernel will refuse creation of the bus. Example:
      <literal>1047-foobar</literal> is an acceptable name for a bus
      registered by a user with UID 1047. However,
      <literal>1024-foobar</literal> is not, and neither is
      <literal>foobar</literal>. The UID must be provided in the
      user-namespace of the bus owner.
    </para>
    <para>
      To create a new bus, you need to open the control file of a domain and
      employ the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl. The control
      file descriptor that was used to issue
      <constant>KDBUS_CMD_BUS_MAKE</constant> must not previously have been
      used for any other control-ioctl and must be kept open for the entire
      life-time of the created bus. Closing it will immediately cleanup the
      entire bus and all its associated resources and endpoints. Every control
      file descriptor can only be used to create a single new bus; from that
      point on, it is not used for any further communication until the final
      <citerefentry>
        <refentrytitle>close</refentrytitle>
        <manvolnum>2</manvolnum>
      </citerefentry>
      .
    </para>
    <para>
      Each bus will generate a random, 128-bit UUID upon creation. This UUID
      will be returned to creators of connections through
      <varname>kdbus_cmd_hello.id128</varname> and can be used to uniquely
      identify buses, even across different machines or containers. The UUID
      will have its variant bits set to <literal>DCE</literal>, and denote
      version 4 (random). For more details on UUIDs, see <ulink
      url="https://en.wikipedia.org/wiki/Universally_unique_identifier">
      the Wikipedia article on UUIDs</ulink>.
    </para>

  </refsect1>

  <refsect1>
    <title>Creating buses</title>
    <para>
      To create a new bus, the <constant>KDBUS_CMD_BUS_MAKE</constant>
      command is used. It takes a <type>struct kdbus_cmd</type> argument.
    </para>
    <programlisting>
struct kdbus_cmd {
  __u64 size;
  __u64 flags;
  __u64 return_flags;
  struct kdbus_item items[0];
};
    </programlisting>

    <para>The fields in this struct are described below.</para>

    <variablelist>
      <varlistentry>
        <term><varname>size</varname></term>
        <listitem><para>
          The overall size of the struct, including its items.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>flags</varname></term>
        <listitem><para>The flags for creation.</para>
          <variablelist>
            <varlistentry>
              <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
              <listitem>
                <para>Make the bus file group-accessible.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
              <listitem>
                <para>Make the bus file world-accessible.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
              <listitem>
                <para>
                  Requests a set of valid flags for this ioctl. When this bit is
                  set, no action is taken; the ioctl will return
                  <errorcode>0</errorcode>, and the <varname>flags</varname>
                  field will have all bits set that are valid for this command.
                  The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
                  cleared by the operation.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>return_flags</varname></term>
        <listitem><para>
          Flags returned by the kernel. Currently unused and always set to
          <constant>0</constant> by the kernel.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>items</varname></term>
        <listitem>
          <para>
            The following items (see
            <citerefentry>
              <refentrytitle>kdbus.item</refentrytitle>
              <manvolnum>7</manvolnum>
            </citerefentry>)
            are expected for <constant>KDBUS_CMD_BUS_MAKE</constant>.
          </para>
          <variablelist>
            <varlistentry>
              <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
              <listitem>
                <para>
                  Contains a null-terminated string that identifies the
                  bus. The name must be unique across the kdbus domain and
                  must start with the effective UID of the caller, followed by
                  a '<literal>-</literal>' (dash). This item is mandatory.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
              <listitem>
                <para>
                  Bus-wide bloom parameters passed in a
                  <type>struct kdbus_bloom_parameter</type>. These settings are
                  copied back to new connections verbatim. This item is
                  mandatory. See
                  <citerefentry>
                    <refentrytitle>kdbus.item</refentrytitle>
                    <manvolnum>7</manvolnum>
                  </citerefentry>
                  for a more detailed description of this item.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
              <listitem>
                <para>
                  An optional item that contains a set of attach flags that are
                  returned to connections when they query the bus creator
                  metadata. If not set, no metadata is returned.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
              <listitem><para>
                With this item, programs can <emphasis>probe</emphasis> the
                kernel for known item types. See
                <citerefentry>
                  <refentrytitle>kdbus.item</refentrytitle>
                  <manvolnum>7</manvolnum>
                </citerefentry>
                for more details.
              </para></listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
      Unrecognized items are rejected, and the ioctl will fail with
      <varname>errno</varname> set to <constant>EINVAL</constant>.
    </para>
  </refsect1>

  <refsect1>
    <title>Return value</title>
    <para>
      On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
      on error, <errorcode>-1</errorcode> is returned, and
      <varname>errno</varname> is set to indicate the error.
      If the issued ioctl is illegal for the file descriptor used,
      <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
    </para>

    <refsect2>
      <title>
        <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following
        errors
      </title>

      <variablelist>
        <varlistentry>
          <term><constant>EBADMSG</constant></term>
          <listitem><para>
            A mandatory item is missing.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>EINVAL</constant></term>
          <listitem><para>
            The flags supplied in the <constant>struct kdbus_cmd</constant>
            are invalid or the supplied name does not start with the current
            UID and a '<literal>-</literal>' (dash).
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>EEXIST</constant></term>
          <listitem><para>
            A bus of that name already exists.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>ESHUTDOWN</constant></term>
          <listitem><para>
            The kdbus mount instance for the bus was already shut down.
          </para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>EMFILE</constant></term>
          <listitem><para>
            The maximum number of buses for the current user is exhausted.
          </para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>kdbus</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.connection</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.endpoint</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.fs</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.item</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.message</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.name</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.pool</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
    </simplelist>
  </refsect1>
</refentry>