messages (see <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
Each bus is independent and operations on the bus will not have any
effect on other buses. A bus is a management entity, that controls the
- addresses of its connections, their policies and message transactions performed
- via this bus.
+ addresses of its connections, their policies and message transactions
+ performed via this bus.
</para>
<para>
- Each bus is bound to the mount instance it was created on. It has a custom name that is
- unique across all buses of a domain. In
+ Each bus is bound to the mount instance it was created on. It has a
+ custom name that is unique across all buses of a domain. In
<citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
a bus is presented as a directory. No operations can be performed on
the bus itself; instead you need to perform the operations on an endpoint
</para>
<para>
Bus names may be chosen freely except for one restriction: the name
- must be prefixed with the numeric effective UID of the creator and a dash. This
- is required to avoid namespace clashes between different users. When creating a
- bus, that name that is passed in must be properly formatted, or the kernel will
- refuse creation of the bus. Example: "1047-foobar" is an acceptable name for a
- bus registered by a user with UID 1047. However, "1024-foobar" is not, and
- neither is "foobar". The UID must be provided in the user-namespace of the
- parent domain.
+ must be prefixed with the numeric effective UID of the creator and a
+ dash. This is required to avoid namespace clashes between different users.
+ When creating a bus, that name that is passed in must be properly
+ formatted, or the kernel will refuse creation of the bus. Example:
+ <constant>"1047-foobar"</constant> is an acceptable name for a bus
+ registered by a user with UID 1047. However,
+ <constant>"1024-foobar"</constant> is not, and neither is
+ <constant>"foobar"</constant>. The UID must be provided in the
+ user-namespace of the bus owner.
</para>
<para>
- To create a new bus, you need to open the control file of a domain and employ
- the <varname>KDBUS_CMD_BUS_MAKE</varname> ioctl. The control file descriptor that was used to issue
- KDBUS_CMD_BUS_MAKE must not previously have been used for any other
- control-ioctl and must be kept open for the entire life-time of the created
- bus. Closing it will immediately cleanup the entire bus and all its associated
- resources and endpoints. Every control file descriptor can only be used to
- create a single new bus; from that point on, it is not used for any further
- communication until the final close().
+ To create a new bus, you need to open the control file of a domain and
+ employ the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl. The control
+ file descriptor that was used to issue
+ <constant>KDBUS_CMD_BUS_MAKE</constant> must not previously have been
+ used for any other control-ioctl and must be kept open for the entire
+ life-time of the created bus. Closing it will immediately cleanup the
+ entire bus and all its associated resources and endpoints. Every control
+ file descriptor can only be used to create a single new bus; from that
+ point on, it is not used for any further communication until the final
+ <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ .
</para>
<para>
Each bus will generate a random, 128-bit UUID upon creation. This UUID will be
<refsect1>
<title>Creating buses and endpoints</title>
<para>
- To create a new bus, the <varname>KDBUS_CMD_BUS_MAKE</varname>
- command is used. It takes a <varname>struct kdbus_cmd_make</varname> argument.
+ To create a new bus, the <constant>KDBUS_CMD_BUS_MAKE</constant>
+ command is used. It takes a <type>struct kdbus_cmd_make</type> argument.
</para>
<programlisting>
struct kdbus_cmd_make {
<listitem><para>The flags for creation.</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_MAKE_ACCESS_GROUP</varname></term>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
<listitem>
<para>Make the bus or endpoint file group-accessible</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_MAKE_ACCESS_WORLD</varname></term>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
<listitem>
<para>Make the bus or endpoint file world-accessible</para>
</listitem>
<para>
The following items (see
<citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
- are expected for <varname>KDBUS_CMD_BUS_MAKE</varname>.
+ are expected for <constant>KDBUS_CMD_BUS_MAKE</constant>.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
<listitem>
<para>
Contains a null-terminated string that identifies the
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_BLOOM_PARAMETER</varname></term>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
<listitem>
<para>
Bus-wide bloom parameters passed in a
- <varname>struct kdbus_bloom_parameter</varname>. These
- settings are copied back to new connections verbatim.
- This item is mandatory.
- See
+ <type>struct kdbus_bloom_parameter</type>. These settings are
+ copied back to new connections verbatim. This item is
+ mandatory. See
<citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- for a detailed description of this item.
+ for a more detailed description of this item.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_ATTACH_FLAGS_RECV</varname></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
<listitem>
<para>An optional item that contains a set of required attach
flags that connections must allow. This item is used as a negotiation
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_ATTACH_FLAGS_SEND</varname></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
<listitem>
<para>
An optional item that contains a set of attach flags that are
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>EINVAL</constant>.
</para>
</refsect1>
<para>
Connections are identified by their <emphasis>connection ID</emphasis>,
- internally implemented as a <varname>uint64_t</varname> counter.
+ internally implemented as a <constant>uint64_t</constant> counter.
The IDs of every newly created bus start at 1, and every new
connection will increment the counter by 1. The IDs are not reused.
</para>
<emphasis>":1.<ID>"</emphasis>.
</para>
<para>
- Messages with a specific <varname>uint64_t</varname> destination ID are
+ Messages with a specific <constant>uint64_t</constant> destination ID are
directly delivered to the connection with the corresponding ID. Messages
- with the special destination ID <varname>KDBUS_DST_ID_BROADCAST</varname>
- (~0ULL) are broadcast messages and are potentially delivered to all
- currently active connections on the bus. However, in order to receive any
- broadcast messages, clients must subscribe to the specific messages they
- are interested in (see
- <citerefentry><refentrytitle>kdbus.match</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ with the special destination ID
+ <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) are broadcast
+ messages and are potentially delivered to all currently active
+ connections on the bus. However, in order to receive any broadcast
+ messages, clients must subscribe to the specific messages they are
+ interested in (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 <varname>KDBUS_SRC_ID_KERNEL</varname> (0).
+ source ID <constant>KDBUS_SRC_ID_KERNEL</constant> (0).
</para>
<para>
- In addition to the unique <varname>uint64_t</varname> connection ID,
+ In addition to the unique <constant>uint64_t</constant> 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
on name acquisition, the name registry, and the validity of names.
</para>
<para>
- Messages can specify the special destination ID <varname>KDBUS_DST_ID_NAME</varname>
- (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.
+ 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[
<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 <varname>KDBUS_CMD_HELLO</varname>
+ 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.
TODO: document precisely what combination of flags may be passed</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_HELLO_ACCEPT_FD</varname></term>
+ <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 results in
- <varname>-ECOMM</varname> on the sender's side.
+ <constant>-ECOMM</constant> on the sender's side.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_HELLO_ACTIVATOR</varname></term>
+ <term><constant>KDBUS_HELLO_ACTIVATOR</constant></term>
<listitem>
<para>
Make this connection an activator (see below). With this bit
- set, an item of type <varname>KDBUS_ITEM_NAME</varname> has
+ 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.
</para>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_HELLO_POLICY_HOLDER</varname></term>
+ <term><constant>KDBUS_HELLO_POLICY_HOLDER</constant></term>
<listitem>
<para>
Make this connection a policy holder (see below). With this
- bit set, an item of type <varname>KDBUS_ITEM_NAME</varname>
+ 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.
</para>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_HELLO_MONITOR</varname></term>
+ <term><constant>KDBUS_HELLO_MONITOR</constant></term>
<listitem>
<para>
Make this connection a monitor (eavesdropping) connection.
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, <varname>-ECONNREFUSED</varname>
- will be returned. In either case, when returning the field will be set
- to the mask of metadata items that are enforced by the bus with the
- <varname>KDBUS_FLAGS_KERNEL</varname> bit set as well.
+ some of those bits to be set. If the match fails, the ioctl will fail
+ with errno 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>
accessed by calling
<citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>
on the file descriptor that was used to issue the
- <varname>KDBUS_CMD_HELLO</varname> ioctl.
+ <constant>KDBUS_CMD_HELLO</constant> ioctl.
</para>
<para>
See
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_CONN_DESCRIPTION</varname></term>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
<listitem>
<para>
Contains a string that describes this connection, so it can
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME</varname></term>
- <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <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
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_CREDS</varname></term>
- <term><varname>KDBUS_ITEM_PIDS</varname></term>
- <term><varname>KDBUS_ITEM_SECLABEL</varname></term>
+ <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
- <varname>KDBUS_CMD_CONN_INFO</varname>. See below for more
+ <constant>KDBUS_CMD_CONN_INFO</constant>. See below for more
information on retrieving information on connections.
</para>
</listitem>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>EINVAL</constant>.
</para>
</listitem>
</varlistentry>
<para>
At the offset returned in the <varname>offset</varname> field of
- <varname>struct kdbus_cmd_hello</varname>, the kernel will store items
+ <type>struct kdbus_cmd_hello</type>, the kernel will store items
of the following types:
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_BLOOM_PARAMETER</varname></term>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
<listitem>
<para>
Bloom filter parameter as defined by the bus creator.
<para>
The offset in the pool has to be freed with the
- <varname>KDBUS_CMD_FREE</varname> ioctl. See
+ <constant>KDBUS_CMD_FREE</constant> ioctl. See
<citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for further information.
</para>
<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 <varname>CAP_IPC_OWNER</varname> set when it called
- <varname>KDBUS_CMD_HELLO</varname>.
+ task had <constant>CAP_IPC_OWNER</constant> set when it called
+ <constant>KDBUS_CMD_HELLO</constant>.
</para>
<para>
Privileged connections have permission to employ certain restricted
<refsect1>
<title>Retrieving information on a connection</title>
<para>
- The <varname>KDBUS_CMD_CONN_INFO</varname> ioctl can be used to retrieve
- credentials and properties of the initial creator of a connection. This
- ioctl uses the following struct.
+ 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>
<listitem><para>
The numerical ID of the connection for which information is to be
retrieved. If set to a non-zero value, the
- <varname>KDBUS_ITEM_OWNED_NAME</varname> item is ignored.
+ <constant>KDBUS_ITEM_OWNED_NAME</constant> item is ignored.
</para></listitem>
</varlistentry>
<listitem>
<para>
The following items are expected for
- <varname>KDBUS_CMD_CONN_INFO</varname>.
+ <constant>KDBUS_CMD_CONN_INFO</constant>.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_OWNED_NAME</varname></term>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
<listitem>
<para>
Contains the well-known name of the connection to look up as.
</variablelist>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>EINVAL</constant>.
</para>
</listitem>
</varlistentry>
<listitem>
<para>
Depending on the <varname>flags</varname> field in
- <varname>struct kdbus_cmd_info</varname>, items of types
- <varname>KDBUS_ITEM_OWNED_NAME</varname> and
- <varname>KDBUS_ITEM_CONN_DESCRIPTION</varname> may follow here.
+ <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.
</para>
</listitem>
</varlistentry>
<para>
Once the caller is finished with parsing the return buffer, it needs to
- employ the <varname>KDBUS_CMD_FREE</varname> command for the offset, in
+ 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 futher information.
<refsect1>
<title>Getting information about a connection's bus creator</title>
<para>
- The <varname>KDBUS_CMD_BUS_CREATOR_INFO</varname> ioctl takes the same
- struct as <varname>KDBUS_CMD_CONN_INFO</varname>, 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.
+ 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 <varname>struct kdbus_info</varname>,
+ filled with an object of type <type>struct kdbus_info</type>,
pointed to by the ioctl's <varname>offset</varname> field.
</para>
<listitem>
<para>
Metadata information is stored in items here. The item list
- contains a <varname>KDBUS_ITEM_MAKE_NAME</varname> item that
+ contains a <constant>KDBUS_ITEM_MAKE_NAME</constant> item that
indicates the bus name of the calling connection.
</para>
</listitem>
<para>
Once the caller is finished with parsing the return buffer, it needs to
- employ the <varname>KDBUS_CMD_FREE</varname> command for the offset, in
+ 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 futher information.
<title>Updating connection details</title>
<para>
Some of a connection's details can be updated with the
- <varname>KDBUS_CMD_CONN_UPDATE</varname> ioctl, using the file
+ <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>
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_ATTACH_FLAGS_SEND</varname></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
<listitem>
<para>
Supply a new set of items that this connection permits to be
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_ATTACH_FLAGS_RECV</varname></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
<listitem>
<para>
Supply a new set of items to be attached to each message.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME</varname></term>
- <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <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,
- <varname>-EOPNOTSUPP</varname> is returned.
+ <constant>EOPNOTSUPP</constant> is returned in errno.
</para>
</listitem>
</varlistentry>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>EINVAL</constant>.
</para>
</listitem>
</varlistentry>
<title>Monitor connections ('eavesdropper')</title>
<para>
Eavesdropping connections are created by setting the
- <varname>KDBUS_HELLO_MONITOR</varname> flag in
+ <constant>KDBUS_HELLO_MONITOR</constant> flag in
<varname>struct kdbus_hello.flags</varname>.
Such connections have all properties of any other, regular connection,
except for the following details:
<listitem><para>
Their creation and destruction will not cause
- <varname>KDBUS_ITEM_ID_{ADD,REMOVE}</varname> notifications to be
+ <constant>KDBUS_ITEM_ID_{ADD,REMOVE}</constant> notifications to be
generated, so other connections cannot detect the presence of an
eavesdropper.
</para></listitem>
<para>
An alternative way of closing down a connection is via the
- <varname>KDBUS_CMD_BYEBYE</varname> ioctl. This ioctl will succeed only
+ <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, <varname>-EBUSY</varname> is returned. When this ioctl returns
+ otherwise, the ioctl will fail with errno set to
+ <constant>EBUSY</constant> is returned. 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.
<refsect1>
<title>Creating custom endpoints</title>
<para>
- To create a new endpoint, the <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>
- command is used. Along with the endpoint's name, which will be used to
- expose the endpoint in the
+ 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>.
- <varname>KDBUS_CMD_ENDPOINT_MAKE</varname> takes a
- <varname>struct kdbus_cmd_make</varname> argument.
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> takes a
+ <type>struct kdbus_cmd_make</type> argument.
</para>
<programlisting>
struct kdbus_cmd_make {
<listitem><para>The flags for creation.</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_MAKE_ACCESS_GROUP</varname></term>
+ <term><constant>KDBUS_MAKE_ACCESS_GROUP</constant></term>
<listitem>
<para>Make the endpoint file group-accessible</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_MAKE_ACCESS_WORLD</varname></term>
+ <term><constant>KDBUS_MAKE_ACCESS_WORLD</constant></term>
<listitem>
<para>Make the endpoint file world-accessible</para>
</listitem>
<listitem>
<para>
The following items are expected for
- <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>.
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_MAKE_NAME</varname></term>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
<listitem>
<para>Contains a string to identify the endpoint name.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME</varname></term>
- <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <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
</variablelist>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <varname>EINVAL</varname>.
</para>
</listitem>
</varlistentry>
<title>Updating endpoints</title>
<para>
To update an existing endpoint, the
- <varname>KDBUS_CMD_ENDPOINT_UPDATE</varname> command is used on the file
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> command is used on the file
descriptor that was used to create the update, using
- <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>. The only relevant detail of
+ <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 <varname>struct kdbus_cmd_update</varname> argument.
+ The command takes a <type>struct kdbus_cmd_update</type> argument.
</para>
<programlisting>
struct kdbus_cmd_make {
<listitem>
<para>
The following items are expected for
- <varname>KDBUS_CMD_ENDPOINT_UPDATE</varname>.
+ <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant>.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME</varname></term>
- <term><varname>KDBUS_ITEM_POLICY_ACCESS</varname></term>
+ <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
</para>
<para>
The system-wide default mount point for <emphasis>kdbusfs</emphasis> is
- <varname>/sys/fs/kdbus</varname>.
+ <constant>/sys/fs/kdbus</constant>.
</para>
<para>
Buses are represented as directories in the file system layout, whereas
endpoints are exposed as files inside these directories. On the top-level,
a <emphasis>control</emphasis> node is present, which can be opened to
- create new buses via the <varname>KDBUS_CMD_BUS_MAKE</varname> ioctl.
+ create new buses via the <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl.
Each <emphasis>bus</emphasis> shows a default endpoint called
<varname>bus</varname>, which can be opened to either create a connection
- with the <varname>KDBUS_CMD_HELLO</varname> ioctl, or to create new
+ with the <constant>KDBUS_CMD_HELLO</constant> ioctl, or to create new
custom endpoints for the bus with
- <varname>KDBUS_CMD_ENDPOINT_MAKE</varname>.
+ <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>.
See
<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry> and
<para>
To flexibly augment transport structures, data blobs of type
- <varname>struct kdbus_item</varname>
- can be attached to the structs passed into the ioctls. Some ioctls make
- items of certain types mandatory, others are optional. Items that are
- unsupported by ioctls they are attached to will cause the ioctl to fail
- <varname>-EINVAL</varname>.
+ <type>struct kdbus_item</type> can be attached to the structs passed
+ into the ioctls. Some ioctls make items of certain types mandatory,
+ others are optional. Items that are unsupported by ioctls they are
+ attached to will cause the ioctl to fail with errno set to
+ <errorname>EINVAL</errorname>.
Items are also used for information stored in a connection's
<emphasis>pool</emphasis>, such as received messages, name lists or
requested connection or bus owner information. Depending on the type of
<para>
The kernel expects all items to be aligned to 8-byte boundaries.
Unaligned items will cause the ioctl they are used with to fail
- with <varname>-EINVAL</varname>. An item that has an unaligned size
- itself hence needs to be padded if it is followed by another item.
+ with errno set to <constant>EINVAL</constant>. An item that has an
+ unaligned size itself hence needs to be padded if it is followed by
+ another item.
</para>
</refsect2>
<refsect1>
<title>Item layout</title>
<para>
- A <varname>struct kdbus_item</varname> consists of a
+ A <type>struct kdbus_item</type> consists of a
<varname>size</varname> field, describing its overall size, and a
<varname>type</varname> field, both 64 bit wide. They are followed by
a union to store information that is specific to the item's type.
</programlisting>
<para>
- <varname>struct kdbus_item</varname> should never be used to allocate
+ <type>struct kdbus_item</type> should never be used to allocate
an item instance, as its size may grow in future releases of the API.
Instead, it should be manually assembled by storing the
<varname>size</varname>, <varname>type</varname> and payload to a
<term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
<listitem><para>
Transports a file descriptor of a <emphasis>memfd</emphasis> in
- <varname>struct kdbus_memfd</varname> in
- <varname>item.memfd</varname>. The <varname>size</varname> field
- has to match the actual size of the memfd that was specified when
- it was created. The <varname>start</varname> parameter denotes the
- offset inside the memfd at which the referenced payload starts. See
+ <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
+ The <varname>size</varname> field has to match the actual size of
+ the memfd that was specified when it was created. The
+ <varname>start</varname> parameter denotes the offset inside the
+ memfd at which the referenced payload starts. See
<citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more information on passing of payload data along with a
message.
the values of this array with valid file descriptor numbers.
When received as item attached to a message, the array will
contain the numbers of the installed file descriptors, or
- <varname>-1</varname> in case an error occured.
+ <constant>-1</constant> in case an error occured.
filedescriptor.
In either case, the number of entries in the array is derived from
the item's total size. See
<term><constant>KDBUS_ITEM_ID</constant></term>
<listitem><para>
Transports a connection's <emphasis>numerical ID</emphasis> of
- a connection as <varname>u64</varname> value in
+ a connection as <constant>u64</constant> value in
<varname>item.id</varname>.
</para></listitem>
</varlistentry>
<listitem><para>
Transports a name associated with the
<emphasis>name registry</emphasis> as null-terminated string as
- <varname>struct kdbus_name</varname> in
+ <type>struct kdbus_name</type> in
<varname>item.name</varname>. The <varname> flags</varname>
contains the flags of the name. See
<citerefentry><refentrytitle>kdbus.name</refentrytitle><manvolnum>7</manvolnum></citerefentry>
Contains both the <emphasis>monotonic</emphasis> and the
<emphasis>realtime</emphasis> timestamp, taken when the message
was processed on the kernel side.
- Stored as <varname>struct kdbus_timestamp</varname> in
+ Stored as <type>struct kdbus_timestamp</type> in
<varname>item.timestamp</varname>.
<programlisting>
struct kdbus_timestamp {
Contains credentials such as the <emphasis>user</emphasis> and
<emphasis>group</emphasis> in the usual four flavors:
real, effective, saved and file-system related.
- Stored as <varname>struct kdbus_creds</varname> in
+ Stored as <type>struct kdbus_creds</type> in
<varname>item.creds</varname>.
<programlisting>
struct kdbus_creds {
<listitem><para>
Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
- Stored as <varname>struct kdbus_pids</varname> in
+ Stored as <type>struct kdbus_pids</type> in
<varname>item.pids</varname>.
<programlisting>
struct kdbus_pids {
<listitem><para>
Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
a remote peer is a member of, stored as array of
- <varname>u32</varname> values in <varname>item.data32</varname>.
+ <type>u32</type> values in <varname>item.data32</varname>.
The array length can be determined by looking at the item's total
size, substracting the size of the header and and dividing the
- remainder by <varname>sizeof(u32)</varname>.
+ remainder by <constant>sizeof(u32)</constant>.
</para></listitem>
</varlistentry>
<term><constant>KDBUS_ITEM_CAPS</constant></term>
<listitem><para>
Contains sets of <emphasis>capabilities</emphasis>, stored as
- <varname>struct kdbus_caps</varname> in
- <varname>item.caps</varname>. As the item size may increas in the
- future, userspace should be written in a way that it takes
+ <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
+ As the item size may increas in the future, userspace should be
+ written in a way that it takes
<varname>item.caps.last_cap</varname> into account, and derive
the number of sets and rows from the item size and the reported
number of valid capability bits.
<listitem><para>
Contains the audit <emphasis>sessionid</emphasis> and
<emphasis>loginuid</emphasis> of a task, stored as
- <varname>struct kdbus_audit</varname> in
+ <type>struct kdbus_audit</type> in
<varname>item.audit</varname>.
<programlisting>
struct kdbus_audit {
<term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
<listitem><para>
Contains the <emphasis>connection description</emphasis>, as set
- by <varname>KDBUS_CMD_HELLO</varname> or
- <varname>KDBUS_CMD_CONN_UPDATE</varname>, stored as
+ by <constant>KDBUS_CMD_HELLO</constant> or
+ <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
null-terminated string in <varname>item.str</varname>. Its length
can also be derived from the item's total size.
</para></listitem>
<title>Matches for broadcast messages from other connections</title>
<para>
A message addressed at the connection ID
- <varname>KDBUS_DST_ID_BROADCAST</varname> (~0ULL) is a broadcast message,
- delivered to all connected peers which installed a rule to match certain
- properties of the message. Without any rules installed in the connection,
- no broadcast message or kernel-side notifications will be delivered
- to the connection. Broadcast messages are subject to policy rules and TALK
- access checks - see
+ <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) is a broadcast
+ message, delivered to all connected peers which installed a rule to
+ match certain properties of the message. Without any rules installed in
+ the connection, no broadcast message or kernel-side notifications will be
+ delivered to the connection. Broadcast messages are subject to policy
+ rules and TALK access checks - see
<citerefentry><refentrytitle>kdbus.policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details on implicit policies.
</para>
<refsect1>
<title>Matches for kernel notifications</title>
<para>
- To add a match, the <varname>KDBUS_CMD_MATCH_ADD</varname> ioctl is used,
- which takes a struct of the struct described below.
+ To add a match, the <constant>KDBUS_CMD_MATCH_ADD</constant> ioctl is
+ used, which takes a struct of the struct described below.
Note that each of the items attached to this command will internally create
one match 'rule', and the collection of them, which is submitted as one block
<listitem><para>Flags to control the behavior of the ioctl.</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_MATCH_REPLACE</varname></term>
+ <term><constant>KDBUS_MATCH_REPLACE</constant></term>
<listitem>
<para>Make the endpoint file group-accessible</para>
</listitem>
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_BLOOM_MASK</varname></term>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
<listitem>
<para>
An item that carries the bloom filter mask to match against
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME</varname></term>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
<listitem>
<para>
Specify a name that a sending connection must own at the
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_ID</varname></term>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
<listitem>
<para>
Specify a sender connection's ID that will match this rule.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_NAME_ADD</varname></term>
- <term><varname>KDBUS_ITEM_NAME_REMOVE</varname></term>
- <term><varname>KDBUS_ITEM_NAME_CHANGE</varname></term>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
<listitem>
<para>
These items request delivery of broadcast messages that
<varname>kdbus_notify_name_change</varname> member.
All information specified must be matched in order to make
the message pass. Use
- <varname>KDBUS_MATCH_ID_ANY</varname> to
+ <constant>KDBUS_MATCH_ID_ANY</constant> to
match against any unique connection ID.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ITEM_ID_ADD</varname></term>
- <term><varname>KDBUS_ITEM_ID_REMOVE</varname></term>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
<listitem>
<para>
These items request delivery of kernel notofications that are
generated when a connection is created or terminated.
- <varname>struct kdbus_notify_id_change</varname>is used to
+ <type>struct kdbus_notify_id_change</type>is used to
store the actual match information. This item can be used to
monitor one particular connection ID, or, when the ID field is set to
- <varname>KDBUS_MATCH_ID_ANY</varname>, all of them.
+ <constant>KDBUS_MATCH_ID_ANY</constant>, all of them.
</para>
</listitem>
</varlistentry>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>-EINVAL</constant>.
</para>
</listitem>
</varlistentry>
<refsect1>
<title>Removing a match</title>
<para>
- Matches can be removed through the
- <varname>KDBUS_CMD_MATCH_REMOVE</varname> ioctl, which takes
- <varname>struct kdbus_cmd_match</varname> as argument, but its fields
+ Matches can be removed with the
+ <constant>KDBUS_CMD_MATCH_REMOVE</constant> ioctl, which takes
+ <type>struct kdbus_cmd_match</type> as argument, but its fields
usage slightly differs compared to that of
- <varname>KDBUS_CMD_MATCH_ADD</varname>.
+ <constant>KDBUS_CMD_MATCH_ADD</constant>.
</para>
<programlisting>
</para>
<para>
Masks are entities that are always passed to the kernel as part of a
- match (with an item of type <varname>KDBUS_ITEM_BLOOM_MASK</varname>),
+ match (with an item of type <constant>KDBUS_ITEM_BLOOM_MASK</constant>),
and filters can be attached to signals, with an item of type
- <varname>KDBUS_ITEM_BLOOM_FILTER</varname>. For a filter to match, all
+ <constant>KDBUS_ITEM_BLOOM_FILTER</constant>. For a filter to match, all
its bits have to be set in the match mask as well.
</para>
<para>
<para>
Hence, in order to catch all messages, a mask filled with
- <varname>0xff</varname> bytes can be installed as a wildcard match rule.
+ <constant>0xff</constant> bytes can be installed as a wildcard match rule.
</para>
<refsect2>
<para>
The <constant>KDBUS_CMD_SEND</constant> ioctl uses a
- <varname>struct kdbus_cmd_send</varname> to describe the message
+ <type>struct kdbus_cmd_send</type> to describe the message
transfer.
</para>
<programlisting>
<term><varname>msg_address</varname></term>
<listitem><para>
In this field, userspace has to provide a pointer to a message
- (<varname>struct kdbus_msg</varname>) to send. See below for a
+ (<type>struct kdbus_msg</type>) to send. See below for a
detailed description.
</para></listitem>
</varlistentry>
<term><varname>reply</varname></term>
<listitem><para>
Only used for synchronous replies. See description of
- <varname>struct kdbus_cmd_recv</varname> for more details.
+ <type>struct kdbus_cmd_recv</type> for more details.
</para></listitem>
</varlistentry>
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ITEM_CANCEL_FD</varname></term>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
<listitem>
<para>
When this optional item is passed in, and the call is
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
on this file descriptor, and if it reports any incoming
bytes, the blocking send operation will be canceled, and the
- call will return <varname>-ECANCELED</varname>. Any type of
- file descriptor on which
+ call will return <errorcode>-1</errorcode> and
+ <varname>errno</varname> will be set to
+ <errorname>ECANCELED</errorname>. Any type of file descriptor
+ on which
<citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>
can be called on can be used as payload to this item.
For asynchronous message sending, this item is allowed but
<para>
With the <constant>KDBUS_CMD_RECV</constant> ioctl, a
- <varname>struct kdbus_cmd_recv</varname> is used.
+ <type>struct kdbus_cmd_recv</type> is used.
</para>
<programlisting>
</variablelist>
<para>
- Both <varname>struct kdbus_cmd_recv</varname> and
- <varname>struct kdbus_cmd_send</varname> embed
- <varname>struct kdbus_msg_info</varname>.
+ Both <type>struct kdbus_cmd_recv</type> and
+ <type>struct kdbus_cmd_send</type> embed
+ <type>struct kdbus_msg_info</type>.
For the <constant>KDBUS_CMD_SEND</constant> ioctl, it is used to catch
synchronous replies, if one was requested, and is unused otherwise.
</para>
Upon successful return of the ioctl, this field contains the size of
the allocated slice at offset <varname>offset</varname>.
It is the combination of the size of the stored
- <varname>struct kdbus_msg</varname> object plus all appended VECs.
+ <type>struct kdbus_msg</type> object plus all appended VECs.
You can use it in combination with <varname>offset</varname> to map
a single message, instead of mapping the entire pool. See
<citerefentry><refentrytitle>kdbus.pool</refentrytitle><manvolnum>7</manvolnum></citerefentry>
Unless <constant>KDBUS_RECV_DROP</constant> was passed after a successful
<constant>KDBUS_CMD_RECV</constant> ioctl, the <varname>offset</varname>
field contains the location of the new message inside the receiver's
- pool. The message is stored as <varname>struct kdbus_msg</varname> at
+ pool. The message is stored as <type>struct kdbus_msg</type> at
this offset, and can be interpreted with the semantics described above.
</para>
<para>
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
- <varname>KDBUS_DST_ID_NAME</varname>, or when a registry dump is
+ <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
requested.
</para>
<title>Acquiring a name</title>
<para>
To acquire a name, a client uses the
- <varname>KDBUS_CMD_NAME_ACQUIRE</varname> ioctl with the following data
+ <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with the following data
structure.
</para>
<listitem><para>Flags to control details in the name acquisition.</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_NAME_REPLACE_EXISTING</varname></term>
+ <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
- <varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname> (see below)
+ <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>).
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname></term>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
<listitem>
<para>
Allow other connections to take over this name. When this
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_QUEUE</varname></term>
+ <term><constant>KDBUS_NAME_QUEUE</constant></term>
<listitem>
<para>
A name that is already acquired by a connection, and which
wasn't requested with the
- <varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname> flag set can
- not be acquired again. 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.
+ <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag set
+ can not be acquired again. 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>
<listitem>
<para>
Items to submit the name. Currently, one item of type
- <varname>KDBUS_ITEM_NAME</varname> is expected and allowed, and
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
the contained string must be a valid bus name.
</para>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
</para>
</listitem>
</varlistentry>
<title>Releasing a name</title>
<para>
A connection may release a name explicitly with the
- <varname>KDBUS_CMD_NAME_RELEASE</varname> ioctl. If the connection was
+ <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
for more information on connections.
</para>
<para>
- The <varname>KDBUS_CMD_NAME_RELEASE</varname> ioctl uses the same data
- structure as the acquisition call (<varname>KDBUS_CMD_NAME_ACQUIRE</varname>),
+ 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>
<listitem>
<para>
Items to submit the name. Currently, one item of type
- <varname>KDBUS_ITEM_NAME</varname> is expected and allowed, and
+ <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
the contained string must be a valid bus name.
</para>
<para>
Unrecognized items are rejected, and the ioctl will fail with
- <varname>-EINVAL</varname>.
+ errno set to <constant>-EINVAL</constant>.
</para>
</listitem>
</varlistentry>
<title>Dumping the name registry</title>
<para>
A connection may request a complete or filtered dump of currently active
- bus names with the <varname>KDBUS_CMD_NAME_LIST</varname> ioctl, which
- takes a <varname>struct kdbus_cmd_name_list</varname> as argument.
+ bus names with the <constant>KDBUS_CMD_NAME_LIST</constant> ioctl, which
+ takes a <type>struct kdbus_cmd_name_list</type> as argument.
</para>
<programlisting>
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_NAME_LIST_UNIQUE</varname></term>
+ <term><constant>KDBUS_NAME_LIST_UNIQUE</constant></term>
<listitem>
<para>
List the unique (numeric) IDs of the connection, whether it
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_LIST_NAMES</varname></term>
+ <term><constant>KDBUS_NAME_LIST_NAMES</constant></term>
<listitem>
<para>
List well-known names stored in the database which are
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_LIST_ACTIVATORS</varname></term>
+ <term><constant>KDBUS_NAME_LIST_ACTIVATORS</constant></term>
<listitem>
<para>
List names that are owned by an activator.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_LIST_QUEUED</varname></term>
+ <term><constant>KDBUS_NAME_LIST_QUEUED</constant></term>
<listitem>
<para>
List connections that are not yet owning a name but are
<para>
The returned list of names is stored in a
- <varname>struct kdbus_name_list</varname> that in turn
+ <type>struct kdbus_name_list</type> that in turn
contains a dynamic number of
- <varname>struct kdbus_cmd_name</varname> that carry the actual
+ <type>struct kdbus_cmd_name</type> that carry the actual
information. The fields inside that
- <varname>struct kdbus_cmd_name</varname> is described next.
+ <type>struct kdbus_cmd_name</type> is described next.
</para>
<programlisting>
<listitem>
<para>
Items containing the actual name. Currently, one item of type
- <varname>KDBUS_ITEM_OWNED_NAME</varname> will be attached,
+ <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><varname>KDBUS_NAME_ALLOW_REPLACEMENT</varname></term>
+ <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
<listitem>
<para>
Other connections are allowed to take over this name from the
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_IN_QUEUE</varname></term>
+ <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
<listitem>
<para>
When retrieving a list of currently acquired names in the
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_NAME_ACTIVATOR</varname></term>
+ <term><constant>KDBUS_NAME_ACTIVATOR</constant></term>
<listitem>
<para>
An activator connection owns a name as a placeholder for an
.
</para>
<para>
- In contrast to <varname>KDBUS_NAME_REPLACE_EXISTING</varname>,
+ 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
control again if the implementer connection terminates.
</para>
<para>
- This flag can not be used when acquiring a name, but is implicitly set
- through <varname>KDBUS_CMD_HELLO</varname> with
- <varname>KDBUS_HELLO_ACTIVATOR</varname> set in
+ 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>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_CMD_HELLO</varname></term>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
<listitem><para>
When creating, or updating, a policy holder connection. See
<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_CMD_ENDPOINT_MAKE</varname></term>
- <term><varname>KDBUS_CMD_ENDPOINT_UPDATE</varname></term>
+ <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
+ <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
<listitem><para>
When creating, or updating, a bus custom endpoint. See
<citerefentry><refentrytitle>kdbus.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
<para>
In all cases, the name and policy access information is stored in items
- of type <varname>KDBUS_ITEM_NAME</varname> and
- <varname>KDBUS_ITEM_POLICY_ACCESS</varname>. For this transport, the
+ of type <constant>KDBUS_ITEM_NAME</constant> and
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
following rules apply.
</para>
<itemizedlist mark="open-circle">
<listitem>
<para>
- An item of type <varname>KDBUS_ITEM_NAME</varname> must be followed
- by at least one <varname>KDBUS_ITEM_POLICY_ACCESS</varname> item.
+ An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
+ by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
</para>
</listitem>
<listitem>
<para>
- An item of type <varname>KDBUS_ITEM_NAME</varname> can be followed
- by an arbitrary number of <varname>KDBUS_ITEM_POLICY_ACCESS</varname>
- items.
+ An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
+ by an arbitrary number of
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
</para>
</listitem>
</itemizedlist>
<para>
- Names passed in items of type <varname>KDBUS_ITEM_NAME</varname> must
+ Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
comply to the rules of valid kdbus names. See
<citerefentry><refentrytitle>kdbus.names</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more information.
- The payload of an item of type <varname>KDBUS_ITEM_POLICY_ACCESS</varname>
- is defined by the following struct. For more information on the layout
- of items, please refer to
+ The payload of an item of type
+ <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
+ struct. For more information on the layout of items, please refer to
<citerefentry><refentrytitle>kdbus.item</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_POLICY_ACCESS_USER</varname></term>
+ <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
<listitem><para>
Grant access to a user with the UID stored in the
<varname>id</varname> field.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_POLICY_ACCESS_GROUP</varname></term>
+ <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
<listitem><para>
Grant access to a user with the GID stored in the
<varname>id</varname> field.
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_POLICY_ACCESS_WORLD</varname></term>
+ <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
<listitem><para>
Grant access to everyone. The <varname>id</varname> field
is ignored.
<variablelist>
<varlistentry>
- <term><varname>KDBUS_POLICY_SEE</varname></term>
+ <term><constant>KDBUS_POLICY_SEE</constant></term>
<listitem><para>
Allow the name to be seen.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_POLICY_TALK</varname></term>
+ <term><constant>KDBUS_POLICY_TALK</constant></term>
<listitem><para>
Allow the name to be talked to.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_POLICY_OWN</varname></term>
+ <term><constant>KDBUS_POLICY_OWN</constant></term>
<listitem><para>
Allow the name to be owned.
</para></listitem>
<varlistentry>
<term><varname>id</varname></term>
<listitem><para>
- For <varname>KDBUS_POLICY_ACCESS_USER</varname>, stores the UID.
- For <varname>KDBUS_POLICY_ACCESS_GROUP</varname>, stores the GID.
+ For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
+ For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
</para></listitem>
</varlistentry>
<refsect1>
<title>Wildcard names</title>
<para>
- Policy holder connections may upload names that contain the wildcard suffix
- <varname>(".*")</varname>. Such a policy entry is effective for every
- well-known name that extends the provided name by exactly one more level.
+ Policy holder connections may upload names that contain the wildcard
+ suffix <constant>(".*")</constant>. Such a policy entry is effective for
+ every well-known name that extends the provided name by exactly one more
+ level.
- For example, the name "foo.bar.*" matches both "foo.bar.baz" and
- "foo.bar.bazbaz" are, but not "foo.bar.baz.baz".
+ For example, the name <constant>"foo.bar.*"</constant> matches both
+ <constant>"foo.bar.baz"</constant> and
+ <constant>"foo.bar.bazbaz"</constant> are, but not
+ <constant>"foo.bar.baz.baz"</constant>.
This allows connections to take control over multiple names that the
policy holder doesn't need to know about when uploading the policy.
<para>
Both the endpoint and the bus policy databases are consulted to allow
name registry listing, owning a well-known name and message delivery.
- If either one fails, the operation is failed with
- <varname>-EPERM</varname>.
+ If either one fails, the operation is failed with errno set to
+ <constant>EPERM</constant>.
For best practices, connections that own names with a restricted TALK
access should not install matches. This avoids cases where the sent
</listitem>
<listitem>
<para>
- Policy rules are always enforced for <varname>TALK</varname> access,
+ Policy rules are always enforced for <constant>TALK</constant> access,
even if both ends are running under the same user. This includes
broadcast messages.
</para>
<listitem>
<para>
To restrict the set of names that can be seen, endpoint policies can
- install <varname>SEE</varname> policies.
+ install <constant>SEE</constant> policies.
</para>
</listitem>
</itemizedlist>
A pool for data received from the kernel is installed for every
<emphasis>connection</emphasis> of the <emphasis>bus</emphasis>, and
is sized according to the information stored in the
- <varname>KDBUS_ITEM_BLOOM_PARAMETER</varname> item that is returned by
- <varname>KDBUS_CMD_HELLO</varname>. Internally, the pool is segmented
+ <constant>KDBUS_ITEM_BLOOM_PARAMETER</constant> item that is returned by
+ <constant>KDBUS_CMD_HELLO</constant>. Internally, the pool is segmented
into <emphasis>slices</emphasis>, each referenced by its
<emphasis>offset</emphasis> in the pool.
</para>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_CMD_HELLO</varname></term>
+ <term><constant>KDBUS_CMD_HELLO</constant></term>
<listitem><para>
... to receive details about the bus the connection was made to
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_CMD_RECV</varname></term>
+ <term><constant>KDBUS_CMD_RECV</constant></term>
<listitem><para>
... to receive a message
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_CMD_NAME_LIST</varname></term>
+ <term><constant>KDBUS_CMD_NAME_LIST</constant></term>
<listitem><para>
... to dump the name registry
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_CMD_CONN_INFO</varname></term>
+ <term><constant>KDBUS_CMD_CONN_INFO</constant></term>
<listitem><para>
... to retrieve information on a connection
</para></listitem>
The <varname>offset</varname> fields returned by either one of the
aforementioned ioctls describe offsets inside the pool. In order to make
the slice available for subsequent calls,
- <varname>KDBUS_CMD_FREE</varname> has to be called on that offset
+ <constant>KDBUS_CMD_FREE</constant> has to be called on that offset
(see below). Otherwise, the pool will fill up, and the connection won't
be able to receive any more information through its pool.
</para>
The <emphasis>file descriptor</emphasis> used to map the memory must be
the one that was used to create the <emphasis>connection</emphasis>
In other words, the one that was used to call
- <varname>KDBUS_CMD_HELLO</varname>. See
+ <constant>KDBUS_CMD_HELLO</constant>. See
<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details.
</para>
<refsect1>
<title>Freeing pool slices</title>
<para>
- The <varname>KDBUS_CMD_FREE</varname> ioctl is used to free a slice
+ The <constant>KDBUS_CMD_FREE</constant> ioctl is used to free a slice
inside the pool, describing an offset that was returned in an
<varname>offset</varname> field of another ioctl struct.
- The <varname>KDBUS_CMD_FREE</varname> command takes a
- <varname>struct kdbus_cmd_free</varname> as argument:
+ The <constant>KDBUS_CMD_FREE</constant> command takes a
+ <type>struct kdbus_cmd_free</type> as argument.
</para>
<programlisting>
<title>Connection</title>
<para>
A connection to a bus is created by opening an endpoint file of a
- bus and becoming an active client with the <varname>HELLO</varname>
- exchange. Every ordinary client 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.
- See
+ bus and becoming an active client with the
+ <constant>KDBUS_CMD_HELLO</constant> exchange. Every ordinary client
+ 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. See
<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details.
</para>
<itemizedlist mark='opencircle'>
<listitem><para>
- When a bus is created (<varname>KDBUS_CMD_MAKE</varname>), information
+ When a bus is created (<constant>KDBUS_CMD_MAKE</constant>), information
about the calling task is collected. This data is returned by the
- kernel via the <varname>KDBUS_CMD_BUS_CREATOR_INFO</varname> call.
+ kernel via the <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> call.
</para></listitem>
<listitem><para>
- When a connection is created (<varname>KDBUS_CMD_HELLO</varname>),
+ When a connection is created (<constant>KDBUS_CMD_HELLO</constant>),
information about the calling task is collected. Alternatively, a
privileged connection may provide 'faked' information about credentials,
PIDs and security labels which will be taken instead. This data is
returned by the kernel as information on a connection
- (<varname>KDBUS_CMD_CONN_INFO</varname>).
+ (<constant>KDBUS_CMD_CONN_INFO</constant>).
</para></listitem>
<listitem><para>
- When a message is sent (<varname>KDBUS_CMD_SEND</varname>), information
+ When a message is sent (<constant>KDBUS_CMD_SEND</constant>), information
about the sending task and the sending connection are collected.
This metadata will be attached to the message when it arrives in the
receiver's pool. If the connection sending the message installed faked
</para></listitem>
<listitem><para>
- [2] When connecting to a bus (<varname>KDBUS_CMD_HELLO</varname>), and
+ [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>), and
(~b & d) != 0, the call will fail, the connection is refused.
</para></listitem>
<variablelist>
<varlistentry>
- <term><varname>KDBUS_ATTACH_TIMESTAMP</varname></term>
+ <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_TIMESTAMP</varname>.
+ <constant>KDBUS_ITEM_TIMESTAMP</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_CREDS</varname></term>
+ <term><constant>KDBUS_ATTACH_CREDS</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_CREDS</varname>.
+ <constant>KDBUS_ITEM_CREDS</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_PIDS</varname></term>
+ <term><constant>KDBUS_ATTACH_PIDS</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_PIDS</varname>.
+ <constant>KDBUS_ITEM_PIDS</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_AUXGROUPS</varname></term>
+ <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_AUXGROUPS</varname>.
+ <constant>KDBUS_ITEM_AUXGROUPS</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_NAMES</varname></term>
+ <term><constant>KDBUS_ATTACH_NAMES</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_OWNED_NAME</varname>.
+ <constant>KDBUS_ITEM_OWNED_NAME</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_TID_COMM</varname></term>
+ <term><constant>KDBUS_ATTACH_TID_COMM</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_TID_COMM</varname>.
+ <constant>KDBUS_ITEM_TID_COMM</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_PID_COMM</varname></term>
+ <term><constant>KDBUS_ATTACH_PID_COMM</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_PID_COMM</varname>.
+ <constant>KDBUS_ITEM_PID_COMM</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_EXE</varname></term>
+ <term><constant>KDBUS_ATTACH_EXE</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_EXE</varname>.
+ <constant>KDBUS_ITEM_EXE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_CMDLINE</varname></term>
+ <term><constant>KDBUS_ATTACH_CMDLINE</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_CMDLINE</varname>.
+ <constant>KDBUS_ITEM_CMDLINE</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_CGROUP</varname></term>
+ <term><constant>KDBUS_ATTACH_CGROUP</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_CGROUP</varname>.
+ <constant>KDBUS_ITEM_CGROUP</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_CAPS</varname></term>
+ <term><constant>KDBUS_ATTACH_CAPS</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_CAPS</varname>.
+ <constant>KDBUS_ITEM_CAPS</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_SECLABEL</varname></term>
+ <term><constant>KDBUS_ATTACH_SECLABEL</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_SECLABEL</varname>.
+ <constant>KDBUS_ITEM_SECLABEL</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_AUDIT</varname></term>
+ <term><constant>KDBUS_ATTACH_AUDIT</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_AUDIT</varname>.
+ <constant>KDBUS_ITEM_AUDIT</constant>.
</para></listitem>
</varlistentry>
<varlistentry>
- <term><varname>KDBUS_ATTACH_CONN_DESCRIPTION</varname></term>
+ <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term>
<listitem><para>
Requests the attachment of an item of type
- <varname>KDBUS_ITEM_CONN_DESCRIPTION</varname>.
+ <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>.
</para></listitem>
</varlistentry>
</variablelist>
projects / platform / core / system / kdbus-bus.git / commitdiff