summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.name.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kdbus/kdbus.name.xml')
-rw-r--r--Documentation/kdbus/kdbus.name.xml711
1 files changed, 711 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.name.xml b/Documentation/kdbus/kdbus.name.xml
new file mode 100644
index 000000000..3f5f6a6c5
--- /dev/null
+++ b/Documentation/kdbus/kdbus.name.xml
@@ -0,0 +1,711 @@
+<?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.name">
+
+ <refentryinfo>
+ <title>kdbus.name</title>
+ <productname>kdbus.name</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.name</refname>
+ <refpurpose>kdbus.name</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ Each
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ instantiates a name registry to resolve well-known names into unique
+ connection IDs for message delivery. The registry will be queried when a
+ message is sent with <varname>kdbus_msg.dst_id</varname> set to
+ <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
+ requested with <constant>KDBUS_CMD_NAME_LIST</constant>.
+ </para>
+
+ <para>
+ All of the below is subject to policy rules for <emphasis>SEE</emphasis>
+ and <emphasis>OWN</emphasis> permissions. See
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Name validity</title>
+ <para>
+ A name has to comply with the following rules in order to be considered
+ valid.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The name has two or more elements separated by a
+ '<literal>.</literal>' (period) character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All elements must contain at least one character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Each element must only contain the ASCII characters
+ <literal>[A-Z][a-z][0-9]_</literal> and must not begin with a
+ digit.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must contain at least one '<literal>.</literal>' (period)
+ character (and thus at least two elements).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not begin with a '<literal>.</literal>' (period)
+ character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The name must not exceed <constant>255</constant> characters in
+ length.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </refsect1>
+
+ <refsect1>
+ <title>Acquiring a name</title>
+ <para>
+ To acquire a name, a client uses the
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with
+ <type>struct kdbus_cmd</type> as 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>Flags to control details in the name acquisition.</para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_REPLACE_EXISTING</constant></term>
+ <listitem>
+ <para>
+ Acquiring a name that is already present usually fails,
+ unless this flag is set in the call, and
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> (see below)
+ was set when the current owner of the name acquired it, or
+ if the current owner is an activator connection (see
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Allow other connections to take over this name. When this
+ happens, the former owner of the connection will be notified
+ of the name loss.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_QUEUE</constant></term>
+ <listitem>
+ <para>
+ A name that is already acquired by a connection can not be
+ acquired again (unless the
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag was
+ set during acquisition; see above).
+ However, a connection can put itself in a queue of
+ connections waiting for the name to be released. Once that
+ happens, the first connection in that queue becomes the new
+ owner and is notified accordingly.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ 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, the following may be
+ returned by the kernel.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ The name was not acquired yet, but the connection was
+ placed in the queue of peers waiting for the name.
+ This can only happen if <constant>KDBUS_NAME_QUEUE</constant>
+ was set in the <varname>flags</varname> member (see above).
+ The connection will receive a name owner change notification
+ once the current owner has given up the name and its
+ ownership was transferred.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items to submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <para>
+ Unrecognized items are rejected, and the ioctl will fail with
+ <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Releasing a name</title>
+ <para>
+ A connection may release a name explicitly with the
+ <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl. If the connection was
+ an implementer of an activatable name, its pending messages are moved
+ back to the activator. If there are any connections queued up as waiters
+ for the name, the first one in the queue (the oldest entry) will become
+ the new owner. The same happens implicitly for all names once a
+ connection terminates. See
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on connections.
+ </para>
+ <para>
+ The <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl uses the same data
+ structure as the acquisition call
+ (<constant>KDBUS_CMD_NAME_ACQUIRE</constant>),
+ but with slightly different field usage.
+ </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>
+ Flags to the command. Currently unused.
+ <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 submit the name. Currently, one item of type
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
+ the contained string must be a valid bus name.
+ <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
+ valid item types. See
+ <citerefentry>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for a detailed description of how this item is used.
+ </para>
+ <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>Dumping the name registry</title>
+ <para>
+ A connection may request a complete or filtered dump of currently active
+ bus names with the <constant>KDBUS_CMD_LIST</constant> ioctl, which
+ takes a <type>struct kdbus_cmd_list</type> as argument.
+ </para>
+
+ <programlisting>
+struct kdbus_cmd_list {
+ __u64 flags;
+ __u64 return_flags;
+ __u64 offset;
+};
+ </programlisting>
+
+ <para>The fields in this struct are described below.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem>
+ <para>
+ Any combination of flags to specify which names should be dumped.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_LIST_UNIQUE</constant></term>
+ <listitem>
+ <para>
+ List the unique (numeric) IDs of the connection, whether it
+ owns a name or not.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_NAMES</constant></term>
+ <listitem>
+ <para>
+ List well-known names stored in the database which are
+ actively owned by a real connection (not an activator).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_ACTIVATORS</constant></term>
+ <listitem>
+ <para>
+ List names that are owned by an activator.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_LIST_QUEUED</constant></term>
+ <listitem>
+ <para>
+ List connections that are not yet owning a name but are
+ waiting for it to become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
+ <listitem>
+ <para>
+ Request a set of valid flags for this ioctl. When this bit is
+ set, no action is taken; the ioctl will fail with
+ <errorcode>-1</errorcode>, and <varname>errno</varname>
+ is set to <constant>EPROTO</constant>.
+ Once the ioctl returned, the <varname>flags</varname>
+ field will have all bits set that the kernel recognizes as
+ 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>offset</varname></term>
+ <listitem><para>
+ When the ioctl returns successfully, the offset to the name registry
+ dump inside the connection's pool will be stored in this field.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The returned list of names is stored in a <type>struct kdbus_list</type>
+ that in turn contains an array of type <type>struct kdbus_info</type>,
+ The array-size in bytes is given as <varname>list_size</varname>.
+ The fields inside <type>struct kdbus_info</type> is described next.
+ </para>
+
+ <programlisting>
+struct kdbus_info {
+ __u64 size;
+ __u64 id;
+ __u64 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>id</varname></term>
+ <listitem><para>
+ The owning connection's unique ID.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>flags</varname></term>
+ <listitem><para>
+ The flags of the owning connection.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>items</varname></term>
+ <listitem>
+ <para>
+ Items containing the actual name. Currently, one item of type
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> will be attached,
+ including the name's flags. In that item, the flags field of the
+ name may carry the following bits:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
+ <listitem>
+ <para>
+ Other connections are allowed to take over this name from the
+ connection that owns it.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
+ <listitem>
+ <para>
+ When retrieving a list of currently acquired names in the
+ registry, this flag indicates whether the connection
+ actually owns the name or is currently waiting for it to
+ become available.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_NAME_ACTIVATOR</constant></term>
+ <listitem>
+ <para>
+ An activator connection owns a name as a placeholder for an
+ implementer, which is started on demand by programs as soon
+ as the first message arrives. There's some more information
+ on this topic in
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ .
+ </para>
+ <para>
+ In contrast to
+ <constant>KDBUS_NAME_REPLACE_EXISTING</constant>,
+ when a name is taken over from an activator connection, all
+ the messages that have been queued in the activator
+ connection will be moved over to the new owner. The activator
+ connection will still be tracked for the name and will take
+ control again if the implementer connection terminates.
+ </para>
+ <para>
+ This flag can not be used when acquiring a name, but is
+ implicitly set through <constant>KDBUS_CMD_HELLO</constant>
+ with <constant>KDBUS_HELLO_ACTIVATOR</constant> set in
+ <varname>kdbus_cmd_hello.conn_flags</varname>.
+ </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>
+ </variablelist>
+
+ <para>
+ The returned buffer must be freed with the
+ <constant>KDBUS_CMD_FREE</constant> ioctl when the user is finished with
+ it. See
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </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_NAME_ACQUIRE</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Illegal command flags, illegal name provided, or an activator
+ tried to acquire a second name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EPERM</constant></term>
+ <listitem><para>
+ Policy prohibited name ownership.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EALREADY</constant></term>
+ <listitem><para>
+ Connection already owns that name.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EEXIST</constant></term>
+ <listitem><para>
+ The name already exists and can not be taken over.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>E2BIG</constant></term>
+ <listitem><para>
+ The maximum number of well-known names per connection is exhausted.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_NAME_RELEASE</constant>
+ may fail with the following errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags, or invalid name provided.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ESRCH</constant></term>
+ <listitem><para>
+ Name is not found in the registry.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>EADDRINUSE</constant></term>
+ <listitem><para>
+ Name is owned by a different connection and can't be released.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>
+ <constant>KDBUS_CMD_LIST</constant> may fail with the following
+ errors
+ </title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>EINVAL</constant></term>
+ <listitem><para>
+ Invalid command flags
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>ENOBUFS</constant></term>
+ <listitem><para>
+ No available memory in the connection's pool.
+ </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.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.item</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>
+ </simplelist>
+ </refsect1>
+</refentry>