ipc/kdbus/Documentation/kdbus.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="kdbus">
   6
   7   <refentryinfo>
   8     <title>kdbus</title>
   9     <productname>kdbus</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus</refname>
  19     <refpurpose>Kernel Message Bus</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Synopsis</title>
  24     <para>
  25       kdbus is an inter-process communication bus system controlled by the
  26       kernel. It provides user-space with an API to create buses and send
  27       unicast and multicast messages to one, or many, peers connected to the
  28       same bus. It does not enforce any layout on the transmitted data, but
  29       only provides the transport layer used for message interchange between
  30       peers.
  31     </para>
  32     <para>
  33       This set of man-pages gives a comprehensive overview of the kernel-level
  34       API, with all ioctl commands, associated structs and bit masks. However,
  35       most people will not use this API level directly, but rather let one of
  36       the high-level abstraction libraries help them integrate D-Bus
  37       functionality into their applications.
  38     </para>
  39   </refsect1>
  40
  41   <refsect1>
  42     <title>Description</title>
  43     <para>
  44       kdbus provides a pseudo filesystem called <emphasis>kdbusfs</emphasis>,
  45       which is usually mounted on <filename>/sys/fs/kdbus</filename>. Bus
  46       primitives can be accessed as files and sub-directories underneath this
  47       mount-point. Any advanced operations are done via
  48       <function>ioctl()</function> on files created by
  49       <emphasis>kdbusfs</emphasis>. Multiple mount-points of
  50       <emphasis>kdbusfs</emphasis> are independent of each other. This allows
  51       namespacing of kdbus by mounting a new instance of
  52       <emphasis>kdbusfs</emphasis> in a new mount-namespace. kdbus calls these
  53       mount instances domains and each bus belongs to exactly one domain.
  54     </para>
  55
  56     <para>
  57       kdbus was designed as a transport layer for D-Bus, but is in no way
  58       limited, nor controlled by the D-Bus protocol specification. The D-Bus
  59       protocol is one possible application layer on top of kdbus.
  60     </para>
  61
  62     <para>
  63       For the general D-Bus protocol specification, its payload format, its
  64       marshaling, and its communication semantics, please refer to the
  65       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">
  66       D-Bus specification</ulink>.
  67     </para>
  68
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>Terminology</title>
  73
  74     <refsect2>
  75       <title>Domain</title>
  76       <para>
  77         A domain is a <emphasis>kdbusfs</emphasis> mount-point containing all
  78         the bus primitives. Each domain is independent, and separate domains
  79         do not affect each other.
  80       </para>
  81     </refsect2>
  82
  83     <refsect2>
  84       <title>Bus</title>
  85       <para>
  86         A bus is a named object inside a domain. Clients exchange messages
  87         over a bus. Multiple buses themselves have no connection to each other;
  88         messages can only be exchanged on the same bus. The default endpoint of
  89         a bus, to which clients establish connections, is the "bus" file
  90         /sys/fs/kdbus/&lt;bus name&gt;/bus.
  91         Common operating system setups create one "system bus" per system,
  92         and one "user bus" for every logged-in user. Applications or services
  93         may create their own private buses. The kernel driver does not
  94         distinguish between different bus types, they are all handled the same
  95         way. See
  96         <citerefentry>
  97           <refentrytitle>kdbus.bus</refentrytitle>
  98           <manvolnum>7</manvolnum>
  99         </citerefentry>
 100         for more details.
 101       </para>
 102     </refsect2>
 103
 104     <refsect2>
 105       <title>Endpoint</title>
 106       <para>
 107         An endpoint provides a file to talk to a bus. Opening an endpoint
 108         creates a new connection to the bus to which the endpoint belongs. All
 109         endpoints have unique names and are accessible as files underneath the
 110         directory of a bus, e.g., /sys/fs/kdbus/&lt;bus&gt;/&lt;endpoint&gt;
 111         Every bus has a default endpoint called "bus".
 112         A bus can optionally offer additional endpoints with custom names
 113         to provide restricted access to the bus. Custom endpoints carry
 114         additional policy which can be used to create sandboxes with
 115         locked-down, limited, filtered access to a bus. See
 116         <citerefentry>
 117           <refentrytitle>kdbus.endpoint</refentrytitle>
 118           <manvolnum>7</manvolnum>
 119         </citerefentry>
 120         for more details.
 121       </para>
 122     </refsect2>
 123
 124     <refsect2>
 125       <title>Connection</title>
 126       <para>
 127         A connection to a bus is created by opening an endpoint file of a
 128         bus. Every ordinary client connection has a unique identifier on the
 129         bus and can address messages to every other connection on the same
 130         bus by using the peer's connection ID as the destination. See
 131         <citerefentry>
 132           <refentrytitle>kdbus.connection</refentrytitle>
 133           <manvolnum>7</manvolnum>
 134         </citerefentry>
 135         for more details.
 136       </para>
 137     </refsect2>
 138
 139     <refsect2>
 140       <title>Pool</title>
 141       <para>
 142         Each connection allocates a piece of shmem-backed memory that is
 143         used to receive messages and answers to ioctl commands from the kernel.
 144         It is never used to send anything to the kernel. In order to access that
 145         memory, an application must mmap() it into its address space. See
 146         <citerefentry>
 147           <refentrytitle>kdbus.pool</refentrytitle>
 148           <manvolnum>7</manvolnum>
 149         </citerefentry>
 150         for more details.
 151       </para>
 152     </refsect2>
 153
 154     <refsect2>
 155       <title>Well-known Name</title>
 156       <para>
 157         A connection can, in addition to its implicit unique connection ID,
 158         request the ownership of a textual well-known name. Well-known names are
 159         noted in reverse-domain notation, such as com.example.service1. A
 160         connection that offers a service on a bus is usually reached by its
 161         well-known name. An analogy of connection ID and well-known name is an
 162         IP address and a DNS name associated with that address. See
 163         <citerefentry>
 164           <refentrytitle>kdbus.name</refentrytitle>
 165           <manvolnum>7</manvolnum>
 166         </citerefentry>
 167         for more details.
 168       </para>
 169     </refsect2>
 170
 171     <refsect2>
 172       <title>Message</title>
 173       <para>
 174         Connections can exchange messages with other connections by addressing
 175         the peers with their connection ID or well-known name. A message
 176         consists of a message header with information on how to route the
 177         message, and the message payload, which is a logical byte stream of
 178         arbitrary size. Messages can carry additional file descriptors to be
 179         passed from one connection to another, just like passing file
 180         descriptors over UNIX domain sockets. Every connection can specify which
 181         set of metadata the kernel should attach to the message when it is
 182         delivered to the receiving connection. Metadata contains information
 183         like: system time stamps, UID, GID, TID, proc-starttime, well-known
 184         names, process comm, process exe, process argv, cgroup, capabilities,
 185         seclabel, audit session, loginuid and the connection's human-readable
 186         name. See
 187         <citerefentry>
 188           <refentrytitle>kdbus.message</refentrytitle>
 189           <manvolnum>7</manvolnum>
 190         </citerefentry>
 191         for more details.
 192       </para>
 193     </refsect2>
 194
 195     <refsect2>
 196       <title>Item</title>
 197       <para>
 198         The API of kdbus implements the notion of items, submitted through and
 199         returned by most ioctls, and stored inside data structures in the
 200         connection's pool. See
 201         <citerefentry>
 202           <refentrytitle>kdbus.item</refentrytitle>
 203           <manvolnum>7</manvolnum>
 204         </citerefentry>
 205         for more details.
 206       </para>
 207     </refsect2>
 208
 209     <refsect2>
 210       <title>Broadcast, signal, filter, match</title>
 211       <para>
 212         Signals are messages that a receiver opts in for by installing a blob of
 213         bytes, called a 'match'. Signal messages must always carry a
 214         counter-part blob, called a 'filter', and signals are only delivered to
 215         peers which have a match that white-lists the message's filter. Senders
 216         of signal messages can use either a single connection ID as receiver,
 217         or the special connection ID
 218         <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
 219         all connections of a bus, following the logic described above. See
 220         <citerefentry>
 221           <refentrytitle>kdbus.match</refentrytitle>
 222           <manvolnum>7</manvolnum>
 223         </citerefentry>
 224         and
 225         <citerefentry>
 226           <refentrytitle>kdbus.message</refentrytitle>
 227           <manvolnum>7</manvolnum>
 228         </citerefentry>
 229         for more details.
 230       </para>
 231     </refsect2>
 232
 233     <refsect2>
 234       <title>Policy</title>
 235       <para>
 236         A policy is a set of rules that define which connections can see, talk
 237         to, or register a well-known name on the bus. A policy is attached to
 238         buses and custom endpoints, and modified by policy holder connections or
 239         owners of custom endpoints. See
 240         <citerefentry>
 241           <refentrytitle>kdbus.policy</refentrytitle>
 242           <manvolnum>7</manvolnum>
 243         </citerefentry>
 244         for more details.
 245       </para>
 246     </refsect2>
 247
 248     <refsect2>
 249       <title>Privileged bus users</title>
 250       <para>
 251         A user connecting to the bus is considered privileged if it is either
 252         the creator of the bus, or if it has the CAP_IPC_OWNER capability flag
 253         set. See
 254         <citerefentry>
 255           <refentrytitle>kdbus.connection</refentrytitle>
 256           <manvolnum>7</manvolnum>
 257         </citerefentry>
 258         for more details.
 259       </para>
 260     </refsect2>
 261   </refsect1>
 262
 263   <refsect1>
 264     <title>Bus Layout</title>
 265
 266     <para>
 267       A <emphasis>bus</emphasis> provides and defines an environment that peers
 268       can connect to for message interchange. A bus is created via the kdbus
 269       control interface and can be modified by the bus creator. It applies the
 270       policy that control all bus operations. The bus creator itself does not
 271       participate as a peer. To establish a peer
 272       <emphasis>connection</emphasis>, you have to open one of the
 273       <emphasis>endpoints</emphasis> of a bus. Each bus provides a default
 274       endpoint, but further endpoints can be created on-demand. Endpoints are
 275       used to apply additional policies for all connections on this endpoint.
 276       Thus, they provide additional filters to further restrict access of
 277       specific connections to the bus.
 278     </para>
 279
 280     <para>
 281       Following, you can see an example bus layout:
 282     </para>
 283
 284     <programlisting><![CDATA[
 285                                   Bus Creator
 286                                        |
 287                                        |
 288                                     +-----+
 289                                     | Bus |
 290                                     +-----+
 291                                        |
 292                     __________________/ \__________________
 293                    /                                       \
 294                    |                                       |
 295              +----------+                             +----------+
 296              | Endpoint |                             | Endpoint |
 297              +----------+                             +----------+
 298          _________/|\_________                   _________/|\_________
 299         /          |          \                 /          |          \
 300         |          |          |                 |          |          |
 301         |          |          |                 |          |          |
 302    Connection  Connection  Connection      Connection  Connection  Connection
 303     ]]></programlisting>
 304
 305   </refsect1>
 306
 307   <refsect1>
 308     <title>Data structures and interconnections</title>
 309     <programlisting><![CDATA[
 310   +--------------------------------------------------------------------------+
 311   | Domain (Mount Point)                                                     |
 312   | /sys/fs/kdbus/control                                                    |
 313   | +----------------------------------------------------------------------+ |
 314   | | Bus (System Bus)                                                     | |
 315   | | /sys/fs/kdbus/0-system/                                              | |
 316   | | +-------------------------------+ +--------------------------------+ | |
 317   | | | Endpoint                      | | Endpoint                       | | |
 318   | | | /sys/fs/kdbus/0-system/bus    | | /sys/fs/kdbus/0-system/ep.app  | | |
 319   | | +-------------------------------+ +--------------------------------+ | |
 320   | | +--------------+ +--------------+ +--------------+ +---------------+ | |
 321   | | | Connection   | | Connection   | | Connection   | | Connection    | | |
 322   | | | :1.22        | | :1.25        | | :1.55        | | :1.81         | | |
 323   | | +--------------+ +--------------+ +--------------+ +---------------+ | |
 324   | +----------------------------------------------------------------------+ |
 325   |                                                                          |
 326   | +----------------------------------------------------------------------+ |
 327   | | Bus (User Bus for UID 2702)                                          | |
 328   | | /sys/fs/kdbus/2702-user/                                             | |
 329   | | +-------------------------------+ +--------------------------------+ | |
 330   | | | Endpoint                      | | Endpoint                       | | |
 331   | | | /sys/fs/kdbus/2702-user/bus   | | /sys/fs/kdbus/2702-user/ep.app | | |
 332   | | +-------------------------------+ +--------------------------------+ | |
 333   | | +--------------+ +--------------+ +--------------+ +---------------+ | |
 334   | | | Connection   | | Connection   | | Connection   | | Connection    | | |
 335   | | | :1.22        | | :1.25        | | :1.55        | | :1.81         | | |
 336   | | +--------------+ +--------------+ +--------------------------------+ | |
 337   | +----------------------------------------------------------------------+ |
 338   +--------------------------------------------------------------------------+
 339     ]]></programlisting>
 340   </refsect1>
 341
 342   <refsect1>
 343     <title>Metadata</title>
 344
 345     <refsect2>
 346       <title>When metadata is collected</title>
 347       <para>
 348         kdbus records data about the system in certain situations. Such metadata
 349         can refer to the currently active process (creds, PIDs, current user
 350         groups, process names and its executable path, cgroup membership,
 351         capabilities, security label and audit information), connection
 352         information (description string, currently owned names) and time stamps.
 353       </para>
 354       <para>
 355         Metadata is collected at the following times.
 356       </para>
 357
 358       <itemizedlist>
 359         <listitem><para>
 360           When a bus is created (<constant>KDBUS_CMD_MAKE</constant>),
 361           information about the calling task is collected. This data is returned
 362           by the kernel via the <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant>
 363           call.
 364         </para></listitem>
 365
 366         <listitem>
 367           <para>
 368             When a connection is created (<constant>KDBUS_CMD_HELLO</constant>),
 369             information about the calling task is collected. Alternatively, a
 370             privileged connection may provide 'faked' information about
 371             credentials, PIDs and security labels which will be stored instead.
 372             This data is returned by the kernel as information on a connection
 373             (<constant>KDBUS_CMD_CONN_INFO</constant>). Only metadata that a
 374             connection allowed to be sent (by setting its bit in
 375             <varname>attach_flags_send</varname>) will be exported in this way.
 376           </para>
 377         </listitem>
 378
 379         <listitem>
 380           <para>
 381             When a message is sent (<constant>KDBUS_CMD_SEND</constant>),
 382             information about the sending task and the sending connection is
 383             collected. This metadata will be attached to the message when it
 384             arrives in the receiver's pool. If the connection sending the
 385             message installed faked credentials (see
 386             <citerefentry>
 387               <refentrytitle>kdbus.connection</refentrytitle>
 388               <manvolnum>7</manvolnum>
 389             </citerefentry>),
 390             the message will not be augmented by any information about the
 391             currently sending task. Note that only metadata that was requested
 392             by the receiving connection will be collected and attached to
 393             messages.
 394           </para>
 395         </listitem>
 396       </itemizedlist>
 397
 398       <para>
 399         Which metadata items are actually delivered depends on the following
 400         sets and masks:
 401       </para>
 402
 403       <itemizedlist>
 404         <listitem><para>
 405           (a) the system-wide kmod creds mask
 406           (module parameter <varname>attach_flags_mask</varname>)
 407         </para></listitem>
 408
 409         <listitem><para>
 410           (b) the per-connection send creds mask, set by the connecting client
 411         </para></listitem>
 412
 413         <listitem><para>
 414           (c) the per-connection receive creds mask, set by the connecting
 415           client
 416         </para></listitem>
 417
 418         <listitem><para>
 419           (d) the per-bus minimal creds mask, set by the bus creator
 420         </para></listitem>
 421
 422         <listitem><para>
 423           (e) the per-bus owner creds mask, set by the bus creator
 424         </para></listitem>
 425
 426         <listitem><para>
 427           (f) the mask specified when querying creds of a bus peer
 428         </para></listitem>
 429
 430         <listitem><para>
 431           (g) the mask specified when querying creds of a bus owner
 432         </para></listitem>
 433       </itemizedlist>
 434
 435       <para>
 436         With the following rules:
 437       </para>
 438
 439       <itemizedlist>
 440         <listitem>
 441           <para>
 442             [1] The creds attached to messages are determined as
 443             <constant>a &amp; b &amp; c</constant>.
 444           </para>
 445         </listitem>
 446
 447         <listitem>
 448           <para>
 449             [2] When connecting to a bus (<constant>KDBUS_CMD_HELLO</constant>),
 450             and <constant>~b &amp; d != 0</constant>, the call will fail with,
 451             <errorcode>-1</errorcode>, and <varname>errno</varname> is set to
 452             <constant>ECONNREFUSED</constant>.
 453           </para>
 454         </listitem>
 455
 456         <listitem>
 457           <para>
 458             [3] When querying creds of a bus peer, the creds returned are
 459             <constant>a &amp; b &amp; f</constant>.
 460           </para>
 461         </listitem>
 462
 463         <listitem>
 464           <para>
 465             [4] When querying creds of a bus owner, the creds returned are
 466             <constant>a &amp; e &amp; g</constant>.
 467           </para>
 468         </listitem>
 469       </itemizedlist>
 470
 471       <para>
 472         Hence, programs might not always get all requested metadata items that
 473         it requested. Code must be written so that it can cope with this fact.
 474       </para>
 475     </refsect2>
 476
 477     <refsect2>
 478       <title>Benefits and heads-up</title>
 479       <para>
 480         Attaching metadata to messages has two major benefits.
 481
 482         <itemizedlist>
 483           <listitem>
 484             <para>
 485               Metadata attached to messages is gathered at the moment when the
 486               other side calls <constant>KDBUS_CMD_SEND</constant>, or,
 487               respectively, then the kernel notification is generated. There is
 488               no need for the receiving peer to retrieve information about the
 489               task in a second step. This closes a race gap that would otherwise
 490               be inherent.
 491             </para>
 492           </listitem>
 493           <listitem>
 494             <para>
 495               As metadata is delivered along with messages in the same data
 496               blob, no extra calls to kernel functions etc. are needed to gather
 497               them.
 498             </para>
 499           </listitem>
 500         </itemizedlist>
 501
 502         Note, however, that collecting metadata does come at a price for
 503         performance, so developers should carefully assess which metadata to
 504         really opt-in for. For best practice, data that is not needed as part
 505         of a message should not be requested by the connection in the first
 506         place (see <varname>attach_flags_recv</varname> in
 507         <constant>KDBUS_CMD_HELLO</constant>).
 508       </para>
 509     </refsect2>
 510
 511     <refsect2>
 512       <title>Attach flags for metadata items</title>
 513       <para>
 514         To let the kernel know which metadata information to attach as items
 515         to the aforementioned commands, it uses a bitmask. In those, the
 516         following <emphasis>attach flags</emphasis> are currently supported.
 517         Both the <varname>attach_flags_recv</varname> and
 518         <varname>attach_flags_send</varname> fields of
 519         <type>struct kdbus_cmd_hello</type>, as well as the payload of the
 520         <constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant> and
 521         <constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant> items follow this
 522         scheme.
 523       </para>
 524
 525       <variablelist>
 526         <varlistentry>
 527           <term><constant>KDBUS_ATTACH_TIMESTAMP</constant></term>
 528             <listitem><para>
 529               Requests the attachment of an item of type
 530               <constant>KDBUS_ITEM_TIMESTAMP</constant>.
 531             </para></listitem>
 532         </varlistentry>
 533
 534         <varlistentry>
 535           <term><constant>KDBUS_ATTACH_CREDS</constant></term>
 536             <listitem><para>
 537               Requests the attachment of an item of type
 538               <constant>KDBUS_ITEM_CREDS</constant>.
 539             </para></listitem>
 540         </varlistentry>
 541
 542         <varlistentry>
 543           <term><constant>KDBUS_ATTACH_PIDS</constant></term>
 544             <listitem><para>
 545               Requests the attachment of an item of type
 546               <constant>KDBUS_ITEM_PIDS</constant>.
 547             </para></listitem>
 548         </varlistentry>
 549
 550         <varlistentry>
 551           <term><constant>KDBUS_ATTACH_AUXGROUPS</constant></term>
 552             <listitem><para>
 553               Requests the attachment of an item of type
 554               <constant>KDBUS_ITEM_AUXGROUPS</constant>.
 555             </para></listitem>
 556         </varlistentry>
 557
 558         <varlistentry>
 559           <term><constant>KDBUS_ATTACH_NAMES</constant></term>
 560             <listitem><para>
 561               Requests the attachment of an item of type
 562               <constant>KDBUS_ITEM_OWNED_NAME</constant>.
 563             </para></listitem>
 564         </varlistentry>
 565
 566         <varlistentry>
 567           <term><constant>KDBUS_ATTACH_TID_COMM</constant></term>
 568             <listitem><para>
 569               Requests the attachment of an item of type
 570               <constant>KDBUS_ITEM_TID_COMM</constant>.
 571             </para></listitem>
 572         </varlistentry>
 573
 574         <varlistentry>
 575           <term><constant>KDBUS_ATTACH_PID_COMM</constant></term>
 576             <listitem><para>
 577               Requests the attachment of an item of type
 578               <constant>KDBUS_ITEM_PID_COMM</constant>.
 579             </para></listitem>
 580         </varlistentry>
 581
 582         <varlistentry>
 583           <term><constant>KDBUS_ATTACH_EXE</constant></term>
 584             <listitem><para>
 585               Requests the attachment of an item of type
 586               <constant>KDBUS_ITEM_EXE</constant>.
 587             </para></listitem>
 588         </varlistentry>
 589
 590         <varlistentry>
 591           <term><constant>KDBUS_ATTACH_CMDLINE</constant></term>
 592             <listitem><para>
 593               Requests the attachment of an item of type
 594               <constant>KDBUS_ITEM_CMDLINE</constant>.
 595             </para></listitem>
 596         </varlistentry>
 597
 598         <varlistentry>
 599           <term><constant>KDBUS_ATTACH_CGROUP</constant></term>
 600             <listitem><para>
 601               Requests the attachment of an item of type
 602               <constant>KDBUS_ITEM_CGROUP</constant>.
 603             </para></listitem>
 604         </varlistentry>
 605
 606         <varlistentry>
 607           <term><constant>KDBUS_ATTACH_CAPS</constant></term>
 608             <listitem><para>
 609               Requests the attachment of an item of type
 610               <constant>KDBUS_ITEM_CAPS</constant>.
 611             </para></listitem>
 612         </varlistentry>
 613
 614         <varlistentry>
 615           <term><constant>KDBUS_ATTACH_SECLABEL</constant></term>
 616             <listitem><para>
 617               Requests the attachment of an item of type
 618               <constant>KDBUS_ITEM_SECLABEL</constant>.
 619             </para></listitem>
 620         </varlistentry>
 621
 622         <varlistentry>
 623           <term><constant>KDBUS_ATTACH_AUDIT</constant></term>
 624             <listitem><para>
 625               Requests the attachment of an item of type
 626               <constant>KDBUS_ITEM_AUDIT</constant>.
 627             </para></listitem>
 628         </varlistentry>
 629
 630         <varlistentry>
 631           <term><constant>KDBUS_ATTACH_CONN_DESCRIPTION</constant></term>
 632             <listitem><para>
 633               Requests the attachment of an item of type
 634               <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant>.
 635             </para></listitem>
 636         </varlistentry>
 637       </variablelist>
 638
 639       <para>
 640         Please refer to
 641         <citerefentry>
 642           <refentrytitle>kdbus.item</refentrytitle>
 643           <manvolnum>7</manvolnum>
 644         </citerefentry>
 645         for detailed information about the layout and payload of items and
 646         what metadata should be used to.
 647       </para>
 648     </refsect2>
 649   </refsect1>
 650
 651   <refsect1>
 652     <title>The ioctl interface</title>
 653
 654     <para>
 655       As stated in the 'synopsis' section above, application developers are
 656       strongly encouraged to use kdbus through one of the high-level D-Bus
 657       abstraction libraries, rather than using the low-level API directly.
 658     </para>
 659
 660     <para>
 661       kdbus on the kernel level exposes its functions exclusively through
 662       <citerefentry>
 663         <refentrytitle>ioctl</refentrytitle>
 664         <manvolnum>2</manvolnum>
 665       </citerefentry>,
 666       employed on file descriptors returned by
 667       <citerefentry>
 668         <refentrytitle>open</refentrytitle>
 669         <manvolnum>2</manvolnum>
 670       </citerefentry>
 671       on pseudo files exposed by
 672       <citerefentry>
 673         <refentrytitle>kdbus.fs</refentrytitle>
 674         <manvolnum>7</manvolnum>
 675       </citerefentry>.
 676     </para>
 677     <para>
 678       Following is a list of all the ioctls, along with the command structs
 679       they must be used with.
 680     </para>
 681
 682     <informaltable frame="none">
 683       <tgroup cols="3" colsep="1">
 684         <thead>
 685           <row>
 686             <entry>ioctl signature</entry>
 687             <entry>command</entry>
 688             <entry>transported struct</entry>
 689           </row>
 690         </thead>
 691         <tbody>
 692           <row>
 693             <entry><constant>0x40189500</constant></entry>
 694             <entry><constant>KDBUS_CMD_BUS_MAKE</constant></entry>
 695             <entry><type>struct kdbus_cmd *</type></entry>
 696           </row><row>
 697             <entry><constant>0x40189510</constant></entry>
 698             <entry><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></entry>
 699             <entry><type>struct kdbus_cmd *</type></entry>
 700           </row><row>
 701             <entry><constant>0xc0609580</constant></entry>
 702             <entry><constant>KDBUS_CMD_HELLO</constant></entry>
 703             <entry><type>struct kdbus_cmd_hello *</type></entry>
 704           </row><row>
 705             <entry><constant>0x40189582</constant></entry>
 706             <entry><constant>KDBUS_CMD_BYEBYE</constant></entry>
 707             <entry><type>struct kdbus_cmd *</type></entry>
 708           </row><row>
 709             <entry><constant>0x40389590</constant></entry>
 710             <entry><constant>KDBUS_CMD_SEND</constant></entry>
 711             <entry><type>struct kdbus_cmd_send *</type></entry>
 712           </row><row>
 713             <entry><constant>0x80409591</constant></entry>
 714             <entry><constant>KDBUS_CMD_RECV</constant></entry>
 715             <entry><type>struct kdbus_cmd_recv *</type></entry>
 716           </row><row>
 717             <entry><constant>0x40209583</constant></entry>
 718             <entry><constant>KDBUS_CMD_FREE</constant></entry>
 719             <entry><type>struct kdbus_cmd_free *</type></entry>
 720           </row><row>
 721             <entry><constant>0x401895a0</constant></entry>
 722             <entry><constant>KDBUS_CMD_NAME_ACQUIRE</constant></entry>
 723             <entry><type>struct kdbus_cmd *</type></entry>
 724           </row><row>
 725             <entry><constant>0x401895a1</constant></entry>
 726             <entry><constant>KDBUS_CMD_NAME_RELEASE</constant></entry>
 727             <entry><type>struct kdbus_cmd *</type></entry>
 728           </row><row>
 729             <entry><constant>0x80289586</constant></entry>
 730             <entry><constant>KDBUS_CMD_LIST</constant></entry>
 731             <entry><type>struct kdbus_cmd_list *</type></entry>
 732           </row><row>
 733             <entry><constant>0x80309584</constant></entry>
 734             <entry><constant>KDBUS_CMD_CONN_INFO</constant></entry>
 735             <entry><type>struct kdbus_cmd_info *</type></entry>
 736           </row><row>
 737             <entry><constant>0x40209551</constant></entry>
 738             <entry><constant>KDBUS_CMD_UPDATE</constant></entry>
 739             <entry><type>struct kdbus_cmd *</type></entry>
 740           </row><row>
 741             <entry><constant>0x80309585</constant></entry>
 742             <entry><constant>KDBUS_CMD_BUS_CREATOR_INFO</constant></entry>
 743             <entry><type>struct kdbus_cmd_info *</type></entry>
 744           </row><row>
 745             <entry><constant>0x40189511</constant></entry>
 746             <entry><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></entry>
 747             <entry><type>struct kdbus_cmd *</type></entry>
 748           </row><row>
 749             <entry><constant>0x402095b0</constant></entry>
 750             <entry><constant>KDBUS_CMD_MATCH_ADD</constant></entry>
 751             <entry><type>struct kdbus_cmd_match *</type></entry>
 752           </row><row>
 753             <entry><constant>0x402095b1</constant></entry>
 754             <entry><constant>KDBUS_CMD_MATCH_REMOVE</constant></entry>
 755             <entry><type>struct kdbus_cmd_match *</type></entry>
 756           </row>
 757         </tbody>
 758       </tgroup>
 759     </informaltable>
 760
 761     <para>
 762       Depending on the type of <emphasis>kdbusfs</emphasis> node that was
 763       opened and what ioctls have been executed on a file descriptor before,
 764       a different sub-set of ioctl commands is allowed.
 765     </para>
 766
 767     <itemizedlist>
 768       <listitem>
 769         <para>
 770           On a file descriptor resulting from opening a
 771           <emphasis>control node</emphasis>, only the
 772           <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl may be executed.
 773         </para>
 774       </listitem>
 775       <listitem>
 776         <para>
 777           On a file descriptor resulting from opening a
 778           <emphasis>bus endpoint node</emphasis>, only the
 779           <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> and
 780           <constant>KDBUS_CMD_HELLO</constant> ioctls may be executed.
 781         </para>
 782       </listitem>
 783       <listitem>
 784         <para>
 785           A file descriptor that was used to create a bus
 786           (via <constant>KDBUS_CMD_BUS_MAKE</constant>) is called a
 787           <emphasis>bus owner</emphasis> file descriptor. The bus will be
 788           active as long as the file descriptor is kept open.
 789           A bus owner file descriptor can not be used to
 790           employ any further ioctls. As soon as
 791           <citerefentry>
 792             <refentrytitle>close</refentrytitle>
 793             <manvolnum>2</manvolnum>
 794           </citerefentry>
 795           is called on it, the bus will be shut down, along will all associated
 796           endpoints and connections. See
 797           <citerefentry>
 798             <refentrytitle>kdbus.bus</refentrytitle>
 799             <manvolnum>7</manvolnum>
 800           </citerefentry>
 801           for more details.
 802         </para>
 803       </listitem>
 804       <listitem>
 805         <para>
 806           A file descriptor that was used to create an endpoint
 807           (via <constant>KDBUS_CMD_ENDPOINT_MAKE</constant>) is called an
 808           <emphasis>endpoint owner</emphasis> file descriptor. The endpoint
 809           will be active as long as the file descriptor is kept open.
 810           An endpoint owner file descriptor can only be used
 811           to update details of an endpoint through the
 812           <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> ioctl. As soon as
 813           <citerefentry>
 814             <refentrytitle>close</refentrytitle>
 815             <manvolnum>2</manvolnum>
 816           </citerefentry>
 817           is called on it, the endpoint will be removed from the bus, and all
 818           connections that are connected to the bus through it are shut down.
 819           See
 820           <citerefentry>
 821             <refentrytitle>kdbus.endpoint</refentrytitle>
 822             <manvolnum>7</manvolnum>
 823           </citerefentry>
 824           for more details.
 825         </para>
 826       </listitem>
 827       <listitem>
 828         <para>
 829           A file descriptor that was used to create a connection
 830           (via <constant>KDBUS_CMD_HELLO</constant>) is called a
 831           <emphasis>connection owner</emphasis> file descriptor. The connection
 832           will be active as long as the file descriptor is kept open.
 833           A connection owner file descriptor may be used to
 834           issue any of the following ioctls.
 835         </para>
 836
 837         <itemizedlist>
 838           <listitem><para>
 839             <constant>KDBUS_CMD_UPDATE</constant> to tweak details of the
 840             connection. See
 841             <citerefentry>
 842               <refentrytitle>kdbus.connection</refentrytitle>
 843               <manvolnum>7</manvolnum>
 844             </citerefentry>.
 845           </para></listitem>
 846
 847           <listitem><para>
 848             <constant>KDBUS_CMD_BYEBYE</constant> to shut down a connection
 849             without losing messages. See
 850             <citerefentry>
 851               <refentrytitle>kdbus.connection</refentrytitle>
 852               <manvolnum>7</manvolnum>
 853             </citerefentry>.
 854           </para></listitem>
 855
 856           <listitem><para>
 857             <constant>KDBUS_CMD_FREE</constant> to free a slice of memory in
 858             the pool. See
 859             <citerefentry>
 860               <refentrytitle>kdbus.pool</refentrytitle>
 861               <manvolnum>7</manvolnum>
 862             </citerefentry>.
 863           </para></listitem>
 864
 865           <listitem><para>
 866             <constant>KDBUS_CMD_CONN_INFO</constant> to retrieve information
 867             on other connections on the bus. See
 868             <citerefentry>
 869               <refentrytitle>kdbus.connection</refentrytitle>
 870               <manvolnum>7</manvolnum>
 871             </citerefentry>.
 872           </para></listitem>
 873
 874           <listitem><para>
 875             <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> to retrieve
 876             information on the bus creator. See
 877             <citerefentry>
 878               <refentrytitle>kdbus.connection</refentrytitle>
 879               <manvolnum>7</manvolnum>
 880             </citerefentry>.
 881           </para></listitem>
 882
 883           <listitem><para>
 884             <constant>KDBUS_CMD_LIST</constant> to retrieve a list of
 885             currently active well-known names and unique IDs on the bus. See
 886             <citerefentry>
 887               <refentrytitle>kdbus.name</refentrytitle>
 888               <manvolnum>7</manvolnum>
 889             </citerefentry>.
 890           </para></listitem>
 891
 892           <listitem><para>
 893             <constant>KDBUS_CMD_SEND</constant> and
 894             <constant>KDBUS_CMD_RECV</constant> to send or receive a message.
 895             See
 896             <citerefentry>
 897               <refentrytitle>kdbus.message</refentrytitle>
 898               <manvolnum>7</manvolnum>
 899             </citerefentry>.
 900           </para></listitem>
 901
 902           <listitem><para>
 903             <constant>KDBUS_CMD_NAME_ACQUIRE</constant> and
 904             <constant>KDBUS_CMD_NAME_RELEASE</constant> to acquire or release
 905             a well-known name on the bus. See
 906             <citerefentry>
 907               <refentrytitle>kdbus.name</refentrytitle>
 908               <manvolnum>7</manvolnum>
 909             </citerefentry>.
 910           </para></listitem>
 911
 912           <listitem><para>
 913             <constant>KDBUS_CMD_MATCH_ADD</constant> and
 914             <constant>KDBUS_CMD_MATCH_REMOVE</constant> to add or remove
 915             a match for signal messages. See
 916             <citerefentry>
 917               <refentrytitle>kdbus.match</refentrytitle>
 918               <manvolnum>7</manvolnum>
 919             </citerefentry>.
 920           </para></listitem>
 921         </itemizedlist>
 922       </listitem>
 923     </itemizedlist>
 924
 925     <para>
 926       These ioctls, along with the structs they transport, are explained in
 927       detail in the other documents linked to in the "See Also" section below.
 928     </para>
 929   </refsect1>
 930
 931   <refsect1>
 932     <title>See Also</title>
 933     <simplelist type="inline">
 934       <member>
 935         <citerefentry>
 936           <refentrytitle>kdbus.bus</refentrytitle>
 937           <manvolnum>7</manvolnum>
 938         </citerefentry>
 939       </member>
 940       <member>
 941         <citerefentry>
 942           <refentrytitle>kdbus.connection</refentrytitle>
 943           <manvolnum>7</manvolnum>
 944         </citerefentry>
 945       </member>
 946       <member>
 947         <citerefentry>
 948           <refentrytitle>kdbus.endpoint</refentrytitle>
 949           <manvolnum>7</manvolnum>
 950         </citerefentry>
 951       </member>
 952       <member>
 953         <citerefentry>
 954           <refentrytitle>kdbus.fs</refentrytitle>
 955           <manvolnum>7</manvolnum>
 956         </citerefentry>
 957       </member>
 958       <member>
 959         <citerefentry>
 960           <refentrytitle>kdbus.item</refentrytitle>
 961           <manvolnum>7</manvolnum>
 962         </citerefentry>
 963       </member>
 964       <member>
 965         <citerefentry>
 966           <refentrytitle>kdbus.message</refentrytitle>
 967           <manvolnum>7</manvolnum>
 968         </citerefentry>
 969       </member>
 970       <member>
 971         <citerefentry>
 972           <refentrytitle>kdbus.name</refentrytitle>
 973           <manvolnum>7</manvolnum>
 974         </citerefentry>
 975       </member>
 976       <member>
 977         <citerefentry>
 978           <refentrytitle>kdbus.pool</refentrytitle>
 979           <manvolnum>7</manvolnum>
 980         </citerefentry>
 981       </member>
 982       <member>
 983         <citerefentry>
 984           <refentrytitle>ioctl</refentrytitle>
 985           <manvolnum>2</manvolnum>
 986         </citerefentry>
 987       </member>
 988       <member>
 989         <citerefentry>
 990           <refentrytitle>mmap</refentrytitle>
 991           <manvolnum>2</manvolnum>
 992         </citerefentry>
 993       </member>
 994       <member>
 995         <citerefentry>
 996           <refentrytitle>open</refentrytitle>
 997           <manvolnum>2</manvolnum>
 998         </citerefentry>
 999       </member>
1000       <member>
1001         <citerefentry>
1002           <refentrytitle>close</refentrytitle>
1003           <manvolnum>2</manvolnum>
1004         </citerefentry>
1005       </member>
1006       <member>
1007         <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>
1008       </member>
1009     </simplelist>
1010   </refsect1>
1011
1012 </refentry>