diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.connection.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.connection.xml | 1252 |
1 files changed, 1252 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.connection.xml b/Documentation/kdbus/kdbus.connection.xml new file mode 100644 index 00000000000..09852125b2d --- /dev/null +++ b/Documentation/kdbus/kdbus.connection.xml @@ -0,0 +1,1252 @@ +<?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. Note, however, that the bus may optionally require + some of those bits to be set. If the match fails, the ioctl will fail + with <varname>errno</varname> set to + <constant>ECONNREFUSED</constant>. In either case, when returning the + field will be set to the mask of metadata items that are enforced by + the bus with the <constant>KDBUS_FLAGS_KERNEL</constant> bit set as + well. + </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>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> + Items to describe the connection details to be updated. 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> |