diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.connection.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.connection.xml | 1244 |
1 files changed, 0 insertions, 1244 deletions
diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml deleted file mode 100644 index 4bb5f30f3..000000000 --- a/Documentation/kdbus/kdbus.connection.xml +++ /dev/null @@ -1,1244 +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.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.<ID>"</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> |