summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.bus.xml
diff options
context:
space:
mode:
authorAndré Fabian Silva Delgado <emulatorman@parabola.nu>2016-02-22 01:12:47 -0300
committerAndré Fabian Silva Delgado <emulatorman@parabola.nu>2016-02-22 01:12:47 -0300
commit6d461a4fe7896faa1aec5a5417888cf179e46b9f (patch)
tree2e0f1a0b7a5418189c8d53592d33a44d0b356fc9 /Documentation/kdbus/kdbus.bus.xml
parent5c545e1fb127a4b11ddc5f1a5ed066b853dd1a1a (diff)
Linux-libre 4.4.2-gnupck-4.4.2-gnu
Diffstat (limited to 'Documentation/kdbus/kdbus.bus.xml')
-rw-r--r--Documentation/kdbus/kdbus.bus.xml344
1 files changed, 0 insertions, 344 deletions
diff --git a/Documentation/kdbus/kdbus.bus.xml b/Documentation/kdbus/kdbus.bus.xml
deleted file mode 100644
index 83f1198bc..000000000
--- a/Documentation/kdbus/kdbus.bus.xml
+++ /dev/null
@@ -1,344 +0,0 @@
-<?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>