| <?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"> |
| |
| <refentryinfo> |
| <title>kdbus</title> |
| <productname>kdbus</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>kdbus</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>kdbus</refname> |
| <refpurpose>Kernel Message Bus</refpurpose> |
| </refnamediv> |
| |
| <refsect1> |
| <title>Synopsis</title> |
| <para> |
| kdbus is an inter-process communication bus system controlled by the |
| kernel. It provides user-space with an API to create buses and send |
| unicast and multicast messages to one, or many, peers connected to the |
| same bus. It does not enforce any layout on the transmitted data, but |
| only provides the transport layer used for message interchange between |
| peers. |
| </para> |
| <para> |
| This set of man-pages gives a comprehensive overview of the kernel-level |
| API, with all ioctl commands, associated structs and bit masks. However, |
| most people will not use this API level directly, but rather let one of |
| the high-level abstraction libraries help them integrate D-Bus |
| functionality into their applications. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Description</title> |
| <para> |
| kdbus provides a pseudo filesystem called <emphasis>kdbusfs</emphasis>, |
| which is usually mounted on <filename>/sys/fs/kdbus</filename>. Bus |
| primitives can be accessed as files and sub-directories underneath this |
| mount-point. Any advanced operations are done via |
| <function>ioctl()</function> on files created by |
| <emphasis>kdbusfs</emphasis>. Multiple mount-points of |
| <emphasis>kdbusfs</emphasis> are independent of each other. This allows |
| namespacing of kdbus by mounting a new instance of |
| <emphasis>kdbusfs</emphasis> in a new mount-namespace. kdbus calls these |
| mount instances domains and each bus belongs to exactly one domain. |
| </para> |
| |
| <para> |
| kdbus was designed as a transport layer for D-Bus, but is in no way |
| limited, nor controlled by the D-Bus protocol specification. The D-Bus |
| protocol is one possible application layer on top of kdbus. |
| </para> |
| |
| <para> |
| For the general D-Bus protocol specification, its payload format, its |
| marshaling, and its communication semantics, please refer to the |
| <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html"> |
| D-Bus specification</ulink>. |
| </para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Terminology</title> |
| |
| <refsect2> |
| <title>Domain</title> |
| <para> |
| A domain is a <emphasis>kdbusfs</emphasis> mount-point containing all |
| the bus primitives. Each domain is independent, and separate domains |
| do not affect each other. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Bus</title> |
| <para> |
| A bus is a named object inside a domain. Clients exchange messages |
| over a bus. Multiple buses themselves have no connection to each other; |
| messages can only be exchanged on the same bus. The default endpoint of |
| a bus, to which clients establish connections, is the "bus" file |
| /sys/fs/kdbus/<bus name>/bus. |
| Common operating system setups create one "system bus" per system, |
| and one "user bus" for every logged-in user. Applications or services |
| may create their own private buses. The kernel driver does not |
| distinguish between different bus types, they are all handled the same |
| way. See |
| <citerefentry> |
| <refentrytitle>kdbus.bus</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Endpoint</title> |
| <para> |
| An endpoint provides a file to talk to a bus. Opening an endpoint |
| creates a new connection to the bus to which the endpoint belongs. All |
| endpoints have unique names and are accessible as files underneath the |
| directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint> |
| Every bus has a default endpoint called "bus". |
| A bus can optionally offer additional endpoints with custom names |
| to provide restricted access to the bus. Custom endpoints carry |
| additional policy which can be used to create sandboxes with |
| locked-down, limited, filtered access to a bus. See |
| <citerefentry> |
| <refentrytitle>kdbus.endpoint</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Connection</title> |
| <para> |
| A connection to a bus is created by opening an endpoint file of a |
| bus. 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> |
| </refsect2> |
| |
| <refsect2> |
| <title>Pool</title> |
| <para> |
| Each connection allocates a piece of shmem-backed memory that is |
| used to receive messages and answers to ioctl commands from the kernel. |
| It is never used to send anything to the kernel. In order to access that |
| memory, an application must mmap() it into its address space. See |
| <citerefentry> |
| <refentrytitle>kdbus.pool</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Well-known Name</title> |
| <para> |
| A connection can, in addition to its implicit unique connection ID, |
| request the ownership of a textual well-known name. Well-known names are |
| noted in reverse-domain notation, such as com.example.service1. A |
| connection that offers a service on a bus is usually reached by its |
| well-known name. An analogy of connection ID and well-known name is an |
| IP address and a DNS name associated with that address. See |
| <citerefentry> |
| <refentrytitle>kdbus.name</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Message</title> |
| <para> |
| Connections can exchange messages with other connections by addressing |
| the peers with their connection ID or well-known name. A message |
| consists of a message header with information on how to route the |
| message, and the message payload, which is a logical byte stream of |
| arbitrary size. Messages can carry additional file descriptors to be |
| passed from one connection to another, just like passing file |
| descriptors over UNIX domain sockets. Every connection can specify which |
| set of metadata the kernel should attach to the message when it is |
| delivered to the receiving connection. Metadata contains information |
| like: system time stamps, UID, GID, TID, proc-starttime, well-known |
| names, process comm, process exe, process argv, cgroup, capabilities, |
| seclabel, audit session, loginuid and the connection's human-readable |
| name. See |
| <citerefentry> |
| <refentrytitle>kdbus.message</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Item</title> |
| <para> |
| The API of kdbus implements the notion of items, submitted through and |
| returned by most ioctls, and stored inside data structures in the |
| connection's pool. See |
| <citerefentry> |
| <refentrytitle>kdbus.item</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Broadcast, signal, filter, match</title> |
| <para> |
| Signals are messages that a receiver opts in for by installing a blob of |
| bytes, called a 'match'. Signal messages must always carry a |
| counter-part blob, called a 'filter', and signals are only delivered to |
| peers which have a match that white-lists the message's filter. Senders |
| of signal messages can use either a single connection ID as receiver, |
| or the special connection ID |
| <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to |
| all connections of a bus, following the logic described above. See |
| <citerefentry> |
| <refentrytitle>kdbus.match</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| and |
| <citerefentry> |
| <refentrytitle>kdbus.message</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Policy</title> |
| <para> |
| A policy is a set of rules that define which connections can see, talk |
| to, or register a well-known name on the bus. A policy is attached to |
| buses and custom endpoints, and modified by policy holder connections or |
| owners of custom endpoints. See |
| <citerefentry> |
| <refentrytitle>kdbus.policy</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Privileged bus users</title> |
| <para> |
| A user connecting to the bus is considered privileged if it is either |
| the creator of the bus, or if it has the CAP_IPC_OWNER capability flag |
| set. See |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>Bus Layout</title> |
| |
| <para> |
| A <emphasis>bus</emphasis> provides and defines an environment that peers |
| can connect to for message interchange. A bus is created via the kdbus |
| control interface and can be modified by the bus creator. It applies the |
| policy that control all bus operations. The bus creator itself does not |
| participate as a peer. To establish a peer |
| <emphasis>connection</emphasis>, you have to open one of the |
| <emphasis>endpoints</emphasis> of a bus. Each bus provides a default |
| endpoint, but further endpoints can be created on-demand. Endpoints are |
| used to apply additional policies for all connections on this endpoint. |
| Thus, they provide additional filters to further restrict access of |
| specific connections to the bus. |
| </para> |
| |
| <para> |
| Following, you can see an example bus layout: |
| </para> |
| |
| <programlisting><![CDATA[ |
| Bus Creator |
| | |
| | |
| +-----+ |
| | Bus | |
| +-----+ |
| | |
| __________________/ \__________________ |
| / \ |
| | | |
| +----------+ +----------+ |
| | Endpoint | | Endpoint | |
| +----------+ +----------+ |
| _________/|\_________ _________/|\_________ |
| / | \ / | \ |
| | | | | | | |
| | | | | | | |
| Connection Connection Connection Connection Connection Connection |
| ]]></programlisting> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Data structures and interconnections</title> |
| <programlisting><![CDATA[ |
| +--------------------------------------------------------------------------+ |
| | Domain (Mount Point) | |
| | /sys/fs/kdbus/control | |
| | +----------------------------------------------------------------------+ | |
| | | Bus (System Bus) | | |
| | | /sys/fs/kdbus/0-system/ | | |
| | | +-------------------------------+ +--------------------------------+ | | |
| | | | Endpoint | | Endpoint | | | |
| | | | /sys/fs/kdbus/0-system/bus | | /sys/fs/kdbus/0-system/ep.app | | | |
| | | +-------------------------------+ +--------------------------------+ | | |
| | | +--------------+ +--------------+ +--------------+ +---------------+ | | |
| | | | Connection | | Connection | | Connection | | Connection | | | |
| | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | | |
| | | +--------------+ +--------------+ +--------------+ +---------------+ | | |
| | +----------------------------------------------------------------------+ | |
| | | |
| | +----------------------------------------------------------------------+ | |
| | | Bus (User Bus for UID 2702) | | |
| | | /sys/fs/kdbus/2702-user/ | | |
| | | +-------------------------------+ +--------------------------------+ | | |
| | | | Endpoint | | Endpoint | | | |
| | | | /sys/fs/kdbus/2702-user/bus | | /sys/fs/kdbus/2702-user/ep.app | | | |
| | | +-------------------------------+ +--------------------------------+ | | |
| | | +--------------+ +--------------+ +--------------+ +---------------+ | | |
| | | | Connection | | Connection | | Connection | | Connection | | | |
| | | | :1.22 | | :1.25 | | :1.55 | | :1.81 | | | |
| | | +--------------+ +--------------+ +--------------------------------+ | | |
| | +----------------------------------------------------------------------+ | |
| +--------------------------------------------------------------------------+ |
| ]]></programlisting> |
| </refsect1> |
| |
| <refsect1> |
| <title>Metadata</title> |
| |
| <refsect2> |
| <title>When metadata is collected</title> |
| <para> |
| kdbus records data about the system in certain situations. Such metadata |
| can refer to the currently active process (creds, PIDs, current user |
| groups, process names and its executable path, cgroup membership, |
| capabilities, security label and audit information), connection |
| information (description string, currently owned names) and time stamps. |
| </para> |
| <para> |
| Metadata is collected at the following times. |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| 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 <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> |
| call. |
| </para></listitem> |
| |
| <listitem> |
| <para> |
| 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 stored instead. |
| This data is returned by the kernel as information on a connection |
| (<constant>KDBUS_CMD_CONN_INFO</constant>). Only metadata that a |
| connection allowed to be sent (by setting its bit in |
| <varname>attach_flags_send</varname>) will be exported in this way. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| When a message is sent (<constant>KDBUS_CMD_SEND</constant>), |
| information about the sending task and the sending connection is |
| 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 credentials (see |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>), |
| the message will not be augmented by any information about the |
| currently sending task. Note that only metadata that was requested |
| by the receiving connection will be collected and attached to |
| messages. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| Which metadata items are actually delivered depends on the following |
| sets and masks: |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| (a) the system-wide kmod creds mask |
| (module parameter <varname>attach_flags_mask</varname>) |
| </para></listitem> |
| |
| <listitem><para> |
| (b) the per-connection send creds mask, set by the connecting client |
| </para></listitem> |
| |
| <listitem><para> |
| (c) the per-connection receive creds mask, set by the connecting |
| client |
| </para></listitem> |
| |
| <listitem><para> |
| (d) the per-bus minimal creds mask, set by the bus creator |
| </para></listitem> |
| |
| <listitem><para> |
| (e) the per-bus owner creds mask, set by the bus creator |
| </para></listitem> |
| |
| <listitem><para> |
| (f) the mask specified when querying creds of a bus peer |
| </para></listitem> |
| |
| <listitem><para> |
| (g) the mask specified when querying creds of a bus owner |
| </para></listitem> |
| </itemizedlist> |
| |
| <para> |
| With the following rules: |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| [1] The creds attached to messages are determined as |
| <constant>a & b & c</constant>. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>), |
| and <constant>~b & d != 0</constant>, the call will fail with, |
| <errorcode>-1</errorcode>, and <varname>errno</varname> is set to |
| <constant>ECONNREFUSED</constant>. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| [3] When querying creds of a bus peer, the creds returned are |
| <constant>a & b & f</constant>. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| [4] When querying creds of a bus owner, the creds returned are |
| <constant>a & e & g</constant>. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| Hence, programs might not always get all requested metadata items that |
| it requested. Code must be written so that it can cope with this fact. |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Benefits and heads-up</title> |
| <para> |
| Attaching metadata to messages has two major benefits. |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| Metadata attached to messages is gathered at the moment when the |
| other side calls <constant>KDBUS_CMD_SEND</constant>, or, |
| respectively, then the kernel notification is generated. There is |
| no need for the receiving peer to retrieve information about the |
| task in a second step. This closes a race gap that would otherwise |
| be inherent. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| As metadata is delivered along with messages in the same data |
| blob, no extra calls to kernel functions etc. are needed to gather |
| them. |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| Note, however, that collecting metadata does come at a price for |
| performance, so developers should carefully assess which metadata to |
| really opt-in for. For best practice, data that is not needed as part |
| of a message should not be requested by the connection in the first |
| place (see <varname>attach_flags_recv</varname> in |
| <constant>KDBUS_CMD_HELLO</constant>). |
| </para> |
| </refsect2> |
| |
| <refsect2> |
| <title>Attach flags for metadata items</title> |
| <para> |
| To let the kernel know which metadata information to attach as items |
| to the aforementioned commands, it uses a bitmask. In those, the |
| following <emphasis>attach flags</emphasis> are currently supported. |
| Both the <varname>attach_flags_recv</varname> and |
| <varname>attach_flags_send</varname> fields of |
| <type>struct kdbus_cmd_hello</type>, as well as the payload of the |
| <constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant> and |
| <constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant> items follow this |
| scheme. |
| </para> |
| |
| <variablelist> |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_TIMESTAMP</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_CREDS</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_CREDS</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_PIDS</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_PIDS</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_AUXGROUPS</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_NAMES</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_OWNED_NAME</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_TID_COMM</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_TID_COMM</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_PID_COMM</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_PID_COMM</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_EXE</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_EXE</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_CMDLINE</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_CMDLINE</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_CGROUP</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_CGROUP</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_CAPS</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_CAPS</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_SECLABEL</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_SECLABEL</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_AUDIT</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_AUDIT</constant>. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term> |
| <listitem><para> |
| Requests the attachment of an item of type |
| <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>. |
| </para></listitem> |
| </varlistentry> |
| </variablelist> |
| |
| <para> |
| Please refer to |
| <citerefentry> |
| <refentrytitle>kdbus.item</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for detailed information about the layout and payload of items and |
| what metadata should be used to. |
| </para> |
| </refsect2> |
| </refsect1> |
| |
| <refsect1> |
| <title>The ioctl interface</title> |
| |
| <para> |
| As stated in the 'synopsis' section above, application developers are |
| strongly encouraged to use kdbus through one of the high-level D-Bus |
| abstraction libraries, rather than using the low-level API directly. |
| </para> |
| |
| <para> |
| kdbus on the kernel level exposes its functions exclusively through |
| <citerefentry> |
| <refentrytitle>ioctl</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry>, |
| employed on file descriptors returned by |
| <citerefentry> |
| <refentrytitle>open</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| on pseudo files exposed by |
| <citerefentry> |
| <refentrytitle>kdbus.fs</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para> |
| <para> |
| Following is a list of all the ioctls, along with the command structs |
| they must be used with. |
| </para> |
| |
| <informaltable frame="none"> |
| <tgroup cols="3" colsep="1"> |
| <thead> |
| <row> |
| <entry>ioctl signature</entry> |
| <entry>command</entry> |
| <entry>transported struct</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><constant>0x40189500</constant></entry> |
| <entry><constant>KDBUS_CMD_BUS_MAKE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x40189510</constant></entry> |
| <entry><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0xc0609580</constant></entry> |
| <entry><constant>KDBUS_CMD_HELLO</constant></entry> |
| <entry><type>struct kdbus_cmd_hello *</type></entry> |
| </row><row> |
| <entry><constant>0x40189582</constant></entry> |
| <entry><constant>KDBUS_CMD_BYEBYE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x40389590</constant></entry> |
| <entry><constant>KDBUS_CMD_SEND</constant></entry> |
| <entry><type>struct kdbus_cmd_send *</type></entry> |
| </row><row> |
| <entry><constant>0x80409591</constant></entry> |
| <entry><constant>KDBUS_CMD_RECV</constant></entry> |
| <entry><type>struct kdbus_cmd_recv *</type></entry> |
| </row><row> |
| <entry><constant>0x40209583</constant></entry> |
| <entry><constant>KDBUS_CMD_FREE</constant></entry> |
| <entry><type>struct kdbus_cmd_free *</type></entry> |
| </row><row> |
| <entry><constant>0x401895a0</constant></entry> |
| <entry><constant>KDBUS_CMD_NAME_ACQUIRE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x401895a1</constant></entry> |
| <entry><constant>KDBUS_CMD_NAME_RELEASE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x80289586</constant></entry> |
| <entry><constant>KDBUS_CMD_LIST</constant></entry> |
| <entry><type>struct kdbus_cmd_list *</type></entry> |
| </row><row> |
| <entry><constant>0x80309584</constant></entry> |
| <entry><constant>KDBUS_CMD_CONN_INFO</constant></entry> |
| <entry><type>struct kdbus_cmd_info *</type></entry> |
| </row><row> |
| <entry><constant>0x40209551</constant></entry> |
| <entry><constant>KDBUS_CMD_UPDATE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x80309585</constant></entry> |
| <entry><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></entry> |
| <entry><type>struct kdbus_cmd_info *</type></entry> |
| </row><row> |
| <entry><constant>0x40189511</constant></entry> |
| <entry><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></entry> |
| <entry><type>struct kdbus_cmd *</type></entry> |
| </row><row> |
| <entry><constant>0x402095b0</constant></entry> |
| <entry><constant>KDBUS_CMD_MATCH_ADD</constant></entry> |
| <entry><type>struct kdbus_cmd_match *</type></entry> |
| </row><row> |
| <entry><constant>0x402095b1</constant></entry> |
| <entry><constant>KDBUS_CMD_MATCH_REMOVE</constant></entry> |
| <entry><type>struct kdbus_cmd_match *</type></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| |
| <para> |
| Depending on the type of <emphasis>kdbusfs</emphasis> node that was |
| opened and what ioctls have been executed on a file descriptor before, |
| a different sub-set of ioctl commands is allowed. |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| On a file descriptor resulting from opening a |
| <emphasis>control node</emphasis>, only the |
| <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl may be executed. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| On a file descriptor resulting from opening a |
| <emphasis>bus endpoint node</emphasis>, only the |
| <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> and |
| <constant>KDBUS_CMD_HELLO</constant> ioctls may be executed. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| A file descriptor that was used to create a bus |
| (via <constant>KDBUS_CMD_BUS_MAKE</constant>) is called a |
| <emphasis>bus owner</emphasis> file descriptor. The bus will be |
| active as long as the file descriptor is kept open. |
| A bus owner file descriptor can not be used to |
| employ any further ioctls. As soon as |
| <citerefentry> |
| <refentrytitle>close</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| is called on it, the bus will be shut down, along will all associated |
| endpoints and connections. See |
| <citerefentry> |
| <refentrytitle>kdbus.bus</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| A file descriptor that was used to create an endpoint |
| (via <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>) is called an |
| <emphasis>endpoint owner</emphasis> file descriptor. The endpoint |
| will be active as long as the file descriptor is kept open. |
| An endpoint owner file descriptor can only be used |
| to update details of an endpoint through the |
| <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> ioctl. As soon as |
| <citerefentry> |
| <refentrytitle>close</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| is called on it, the endpoint will be removed from the bus, and all |
| connections that are connected to the bus through it are shut down. |
| See |
| <citerefentry> |
| <refentrytitle>kdbus.endpoint</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| for more details. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| A file descriptor that was used to create a connection |
| (via <constant>KDBUS_CMD_HELLO</constant>) is called a |
| <emphasis>connection owner</emphasis> file descriptor. The connection |
| will be active as long as the file descriptor is kept open. |
| A connection owner file descriptor may be used to |
| issue any of the following ioctls. |
| </para> |
| |
| <itemizedlist> |
| <listitem><para> |
| <constant>KDBUS_CMD_UPDATE</constant> to tweak details of the |
| connection. See |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_BYEBYE</constant> to shut down a connection |
| without losing messages. See |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_FREE</constant> to free a slice of memory in |
| the pool. See |
| <citerefentry> |
| <refentrytitle>kdbus.pool</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_CONN_INFO</constant> to retrieve information |
| on other connections on the bus. See |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> to retrieve |
| information on the bus creator. See |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_LIST</constant> to retrieve a list of |
| currently active well-known names and unique IDs on the bus. See |
| <citerefentry> |
| <refentrytitle>kdbus.name</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_SEND</constant> and |
| <constant>KDBUS_CMD_RECV</constant> to send or receive a message. |
| See |
| <citerefentry> |
| <refentrytitle>kdbus.message</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_NAME_ACQUIRE</constant> and |
| <constant>KDBUS_CMD_NAME_RELEASE</constant> to acquire or release |
| a well-known name on the bus. See |
| <citerefentry> |
| <refentrytitle>kdbus.name</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| |
| <listitem><para> |
| <constant>KDBUS_CMD_MATCH_ADD</constant> and |
| <constant>KDBUS_CMD_MATCH_REMOVE</constant> to add or remove |
| a match for signal messages. See |
| <citerefentry> |
| <refentrytitle>kdbus.match</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry>. |
| </para></listitem> |
| </itemizedlist> |
| </listitem> |
| </itemizedlist> |
| |
| <para> |
| These ioctls, along with the structs they transport, are explained in |
| detail in the other documents linked to in the "See Also" section below. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <simplelist type="inline"> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.bus</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.connection</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.endpoint</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.fs</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.item</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.message</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.name</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>kdbus.pool</refentrytitle> |
| <manvolnum>7</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>ioctl</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>mmap</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>open</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <citerefentry> |
| <refentrytitle>close</refentrytitle> |
| <manvolnum>2</manvolnum> |
| </citerefentry> |
| </member> |
| <member> |
| <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink> |
| </member> |
| </simplelist> |
| </refsect1> |
| |
| </refentry> |
