diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.xml | 1012 |
1 files changed, 0 insertions, 1012 deletions
diff --git a/Documentation/kdbus/kdbus.xml b/Documentation/kdbus/kdbus.xml deleted file mode 100644 index d8e7400df..000000000 --- a/Documentation/kdbus/kdbus.xml +++ /dev/null @@ -1,1012 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<refentry id="kdbus"> - - <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> |