diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.endpoint.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.endpoint.xml | 429 |
1 files changed, 0 insertions, 429 deletions
diff --git a/Documentation/kdbus/kdbus.endpoint.xml b/Documentation/kdbus/kdbus.endpoint.xml deleted file mode 100644 index 6632485f3..000000000 --- a/Documentation/kdbus/kdbus.endpoint.xml +++ /dev/null @@ -1,429 +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.endpoint"> - - <refentryinfo> - <title>kdbus.endpoint</title> - <productname>kdbus.endpoint</productname> - </refentryinfo> - - <refmeta> - <refentrytitle>kdbus.endpoint</refentrytitle> - <manvolnum>7</manvolnum> - </refmeta> - - <refnamediv> - <refname>kdbus.endpoint</refname> - <refpurpose>kdbus endpoint</refpurpose> - </refnamediv> - - <refsect1> - <title>Description</title> - - <para> - Endpoints are entry points to a bus (see - <citerefentry> - <refentrytitle>kdbus.bus</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>). - By default, each bus has a default - endpoint called 'bus'. The bus owner has the ability to create custom - endpoints with specific names, permissions, and policy databases - (see below). An endpoint is presented as file underneath the directory - of the parent bus. - </para> - <para> - To create a custom endpoint, open the default endpoint - (<literal>bus</literal>) and use the - <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> ioctl with - <type>struct kdbus_cmd</type>. Custom endpoints always have a policy - database that, by default, forbids any operation. You have to explicitly - install policy entries to allow any operation on this endpoint. - </para> - <para> - Once <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> succeeded, the new - endpoint will appear in the filesystem - (<citerefentry> - <refentrytitle>kdbus.bus</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>), and the used file descriptor will manage the - newly created endpoint resource. It cannot be used to manage further - resources and must be kept open as long as the endpoint is needed. The - endpoint will be terminated as soon as the file descriptor is closed. - </para> - <para> - Endpoint 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 an endpoint, the name that is passed in must be properly - formatted or the kernel will refuse creation of the endpoint. Example: - <literal>1047-my-endpoint</literal> is an acceptable name for an - endpoint registered by a user with UID 1047. However, - <literal>1024-my-endpoint</literal> is not, and neither is - <literal>my-endpoint</literal>. The UID must be provided in the - user-namespace of the bus. - </para> - <para> - To create connections to a bus, use <constant>KDBUS_CMD_HELLO</constant> - on a file descriptor returned by <function>open()</function> on an - endpoint node. See - <citerefentry> - <refentrytitle>kdbus.connection</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry> - for further details. - </para> - </refsect1> - - <refsect1> - <title>Creating custom endpoints</title> - <para> - To create a new endpoint, the - <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> command is used. Along with - the endpoint's name, which will be used to expose the endpoint in the - <citerefentry> - <refentrytitle>kdbus.fs</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>, - the command also optionally takes items to set up the endpoint's - <citerefentry> - <refentrytitle>kdbus.policy</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>. - <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> 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 endpoint file group-accessible.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term> - <listitem> - <para>Make the endpoint 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 are expected for - <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. - </para> - <variablelist> - <varlistentry> - <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term> - <listitem> - <para>Contains a string to identify the endpoint name.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><constant>KDBUS_ITEM_NAME</constant></term> - <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term> - <listitem> - <para> - These items are used to set the policy attached to the - endpoint. For more details on bus and endpoint policies, see - <citerefentry> - <refentrytitle>kdbus.policy</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - Unrecognized items are rejected, and the ioctl will fail with - <varname>errno</varname> set to <varname>EINVAL</varname>. - </para> - </listitem> - </varlistentry> - </variablelist> - </refsect1> - - <refsect1> - <title>Updating endpoints</title> - <para> - To update an existing endpoint, the - <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file - descriptor that was used to create the endpoint, using - <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>. The only relevant detail of - the endpoint that can be updated is the policy. When the command is - employed, the policy of the endpoint is <emphasis>replaced</emphasis> - atomically with the new set of rules. - The command 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> - Unused for this command. - <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> - The following items are expected for - <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>. - </para> - <variablelist> - <varlistentry> - <term><constant>KDBUS_ITEM_NAME</constant></term> - <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term> - <listitem> - <para> - These items are used to set the policy attached to the - endpoint. For more details on bus and endpoint policies, see - <citerefentry> - <refentrytitle>kdbus.policy</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry>. - Existing policy is atomically replaced with the new rules - provided. - </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>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_ENDPOINT_MAKE</constant> may fail with the - following errors - </title> - - <variablelist> - <varlistentry> - <term><constant>EINVAL</constant></term> - <listitem><para> - The flags supplied in the <type>struct kdbus_cmd</type> - are invalid. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>EINVAL</constant></term> - <listitem><para> - Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and - <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>EEXIST</constant></term> - <listitem><para> - An endpoint of that name already exists. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>EPERM</constant></term> - <listitem><para> - The calling user is not privileged. See - <citerefentry> - <refentrytitle>kdbus</refentrytitle> - <manvolnum>7</manvolnum> - </citerefentry> - for information about privileged users. - </para></listitem> - </varlistentry> - </variablelist> - </refsect2> - - <refsect2> - <title> - <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the - following errors - </title> - - <variablelist> - <varlistentry> - <term><constant>EINVAL</constant></term> - <listitem><para> - The flags supplied in <type>struct kdbus_cmd</type> - are invalid. - </para></listitem> - </varlistentry> - - <varlistentry> - <term><constant>EINVAL</constant></term> - <listitem><para> - Illegal combination of <constant>KDBUS_ITEM_NAME</constant> and - <constant>KDBUS_ITEM_POLICY_ACCESS</constant> was provided. - </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.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> |