ipc/kdbus/Documentation/kdbus.connection.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.connection">
   6
   7   <refentryinfo>
   8     <title>kdbus.connection</title>
   9     <productname>kdbus.connection</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.connection</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.connection</refname>
  19     <refpurpose>kdbus connection</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>
  26       Connections are identified by their <emphasis>connection ID</emphasis>,
  27       internally implemented as a <type>uint64_t</type> counter.
  28       The IDs of every newly created bus start at <constant>1</constant>, and
  29       every new connection will increment the counter by <constant>1</constant>.
  30       The IDs are not reused.
  31     </para>
  32     <para>
  33       In higher level tools, the user visible representation of a connection is
  34       defined by the D-Bus protocol specification as
  35       <constant>":1.&lt;ID&gt;"</constant>.
  36     </para>
  37     <para>
  38       Messages with a specific <type>uint64_t</type> destination ID are
  39       directly delivered to the connection with the corresponding ID. Signal
  40       messages (see
  41       <citerefentry>
  42         <refentrytitle>kdbus.message</refentrytitle>
  43         <manvolnum>7</manvolnum>
  44       </citerefentry>)
  45       may be addressed to the special destination ID
  46       <constant>KDBUS_DST_ID_BROADCAST</constant> (~0ULL) and will then
  47       potentially be delivered to all currently active connections on the bus.
  48       However, in order to receive any signal messages, clients must subscribe
  49       to them by installing a match (see
  50       <citerefentry>
  51         <refentrytitle>kdbus.match</refentrytitle>
  52         <manvolnum>7</manvolnum>
  53       </citerefentry>).
  54     </para>
  55     <para>
  56       Messages synthesized and sent directly by the kernel will carry the
  57       special source ID <constant>KDBUS_SRC_ID_KERNEL</constant> (0).
  58     </para>
  59     <para>
  60       In addition to the unique <type>uint64_t</type> connection ID,
  61       established connections can request the ownership of
  62       <emphasis>well-known names</emphasis>, under which they can be found and
  63       addressed by other bus clients. A well-known name is associated with one
  64       and only one connection at a time. See
  65       <citerefentry>
  66         <refentrytitle>kdbus.name</refentrytitle>
  67         <manvolnum>7</manvolnum>
  68       </citerefentry>
  69       on name acquisition, the name registry, and the validity of names.
  70     </para>
  71     <para>
  72       Messages can specify the special destination ID
  73       <constant>KDBUS_DST_ID_NAME</constant> (0) and carry a well-known name
  74       in the message data. Such a message is delivered to the destination
  75       connection which owns that well-known name.
  76     </para>
  77
  78     <programlisting><![CDATA[
  79   +-------------------------------------------------------------------------+
  80   | +---------------+     +---------------------------+                     |
  81   | | Connection    |     | Message                   | -----------------+  |
  82   | | :1.22         | --> | src: 22                   |                  |  |
  83   | |               |     | dst: 25                   |                  |  |
  84   | |               |     |                           |                  |  |
  85   | |               |     |                           |                  |  |
  86   | |               |     +---------------------------+                  |  |
  87   | |               |                                                    |  |
  88   | |               | <--------------------------------------+           |  |
  89   | +---------------+                                        |           |  |
  90   |                                                          |           |  |
  91   | +---------------+     +---------------------------+      |           |  |
  92   | | Connection    |     | Message                   | -----+           |  |
  93   | | :1.25         | --> | src: 25                   |                  |  |
  94   | |               |     | dst: 0xffffffffffffffff   | -------------+   |  |
  95   | |               |     |  (KDBUS_DST_ID_BROADCAST) |              |   |  |
  96   | |               |     |                           | ---------+   |   |  |
  97   | |               |     +---------------------------+          |   |   |  |
  98   | |               |                                            |   |   |  |
  99   | |               | <--------------------------------------------------+  |
 100   | +---------------+                                            |   |      |
 101   |                                                              |   |      |
 102   | +---------------+     +---------------------------+          |   |      |
 103   | | Connection    |     | Message                   | --+      |   |      |
 104   | | :1.55         | --> | src: 55                   |   |      |   |      |
 105   | |               |     | dst: 0 / org.foo.bar      |   |      |   |      |
 106   | |               |     |                           |   |      |   |      |
 107   | |               |     |                           |   |      |   |      |
 108   | |               |     +---------------------------+   |      |   |      |
 109   | |               |                                     |      |   |      |
 110   | |               | <------------------------------------------+   |      |
 111   | +---------------+                                     |          |      |
 112   |                                                       |          |      |
 113   | +---------------+                                     |          |      |
 114   | | Connection    |                                     |          |      |
 115   | | :1.81         |                                     |          |      |
 116   | | org.foo.bar   |                                     |          |      |
 117   | |               |                                     |          |      |
 118   | |               |                                     |          |      |
 119   | |               | <-----------------------------------+          |      |
 120   | |               |                                                |      |
 121   | |               | <----------------------------------------------+      |
 122   | +---------------+                                                       |
 123   +-------------------------------------------------------------------------+
 124     ]]></programlisting>
 125   </refsect1>
 126
 127   <refsect1>
 128     <title>Privileged connections</title>
 129     <para>
 130       A connection is considered <emphasis>privileged</emphasis> if the user
 131       it was created by is the same that created the bus, or if the creating
 132       task had <constant>CAP_IPC_OWNER</constant> set when it called
 133       <constant>KDBUS_CMD_HELLO</constant> (see below).
 134     </para>
 135     <para>
 136       Privileged connections have permission to employ certain restricted
 137       functions and commands, which are explained below and in other kdbus
 138       man-pages.
 139     </para>
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>Activator and policy holder connection</title>
 144     <para>
 145       An <emphasis>activator</emphasis> connection is a placeholder for a
 146       <emphasis>well-known name</emphasis>. Messages sent to such a connection
 147       can be used to start an implementer connection, which will then get all
 148       the messages from the activator copied over. An activator connection
 149       cannot be used to send any message.
 150     </para>
 151     <para>
 152       A <emphasis>policy holder</emphasis> connection only installs a policy
 153       for one or more names. These policy entries are kept active as long as
 154       the connection is alive, and are removed once it terminates. Such a
 155       policy connection type can be used to deploy restrictions for names that
 156       are not yet active on the bus. A policy holder connection cannot be used
 157       to send any message.
 158     </para>
 159     <para>
 160       The creation of activator or policy holder connections is restricted to
 161       privileged users on the bus (see above).
 162     </para>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Monitor connections</title>
 167     <para>
 168       Monitors are eavesdropping connections that receive all the traffic on the
 169       bus, but is invisible to other connections. Such connections have all
 170       properties of any other, regular connection, except for the following
 171       details:
 172     </para>
 173
 174     <itemizedlist>
 175       <listitem><para>
 176         They will get every message sent over the bus, both unicasts and
 177         broadcasts.
 178       </para></listitem>
 179
 180       <listitem><para>
 181         Installing matches for signal messages is neither necessary
 182         nor allowed.
 183       </para></listitem>
 184
 185       <listitem><para>
 186         They cannot send messages or be directly addressed as receiver.
 187       </para></listitem>
 188
 189       <listitem><para>
 190         They cannot own well-known names. Therefore, they also can't operate as
 191         activators.
 192       </para></listitem>
 193
 194       <listitem><para>
 195         Their creation and destruction will not cause
 196         <constant>KDBUS_ITEM_ID_{ADD,REMOVE}</constant> (see
 197         <citerefentry>
 198           <refentrytitle>kdbus.item</refentrytitle>
 199           <manvolnum>7</manvolnum>
 200         </citerefentry>).
 201       </para></listitem>
 202
 203       <listitem><para>
 204         They are not listed with their unique name in name registry dumps
 205         (see <constant>KDBUS_CMD_NAME_LIST</constant> in
 206         <citerefentry>
 207           <refentrytitle>kdbus.name</refentrytitle>
 208           <manvolnum>7</manvolnum>
 209         </citerefentry>), so other connections cannot detect the presence of
 210         a monitor.
 211       </para></listitem>
 212     </itemizedlist>
 213     <para>
 214       The creation of monitor connections is restricted to privileged users on
 215       the bus (see above).
 216     </para>
 217   </refsect1>
 218
 219   <refsect1>
 220     <title>Creating connections</title>
 221     <para>
 222       A connection to a bus is created by opening an endpoint file (see
 223       <citerefentry>
 224         <refentrytitle>kdbus.endpoint</refentrytitle>
 225         <manvolnum>7</manvolnum>
 226       </citerefentry>)
 227       of a bus and becoming an active client with the
 228       <constant>KDBUS_CMD_HELLO</constant> ioctl. Every connection has a unique
 229       identifier on the bus and can address messages to every other connection
 230       on the same bus by using the peer's connection ID as the destination.
 231     </para>
 232     <para>
 233       The <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
 234       kdbus_cmd_hello</type> as argument.
 235     </para>
 236
 237     <programlisting>
 238 struct kdbus_cmd_hello {
 239   __u64 size;
 240   __u64 flags;
 241   __u64 return_flags;
 242   __u64 attach_flags_send;
 243   __u64 attach_flags_recv;
 244   __u64 bus_flags;
 245   __u64 id;
 246   __u64 pool_size;
 247   __u64 offset;
 248   __u8 id128[16];
 249   struct kdbus_item items[0];
 250 };
 251     </programlisting>
 252
 253     <para>The fields in this struct are described below.</para>
 254
 255     <variablelist>
 256       <varlistentry>
 257         <term><varname>size</varname></term>
 258         <listitem><para>
 259           The overall size of the struct, including its items.
 260         </para></listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><varname>flags</varname></term>
 265         <listitem>
 266           <para>Flags to apply to this connection</para>
 267           <variablelist>
 268             <varlistentry>
 269               <term><constant>KDBUS_HELLO_ACCEPT_FD</constant></term>
 270               <listitem>
 271                 <para>
 272                   When this flag is set, the connection can be sent file
 273                   descriptors as message payload of unicast messages. If it's
 274                   not set, an attempt to send file descriptors will result in
 275                   <constant>-ECOMM</constant> on the sender's side.
 276                 </para>
 277               </listitem>
 278             </varlistentry>
 279
 280             <varlistentry>
 281               <term><constant>KDBUS_HELLO_ACTIVATOR</constant></term>
 282               <listitem>
 283                 <para>
 284                   Make this connection an activator (see above). With this bit
 285                   set, an item of type <constant>KDBUS_ITEM_NAME</constant> has
 286                   to be attached. This item describes the well-known name this
 287                   connection should be an activator for.
 288                   A connection can not be an activator and a policy holder at
 289                   the same time time, so this bit is not allowed together with
 290                   <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
 291                 </para>
 292               </listitem>
 293             </varlistentry>
 294
 295             <varlistentry>
 296               <term><constant>KDBUS_HELLO_POLICY_HOLDER</constant></term>
 297               <listitem>
 298                 <para>
 299                   Make this connection a policy holder (see above). With this
 300                   bit set, an item of type <constant>KDBUS_ITEM_NAME</constant>
 301                   has to be attached. This item describes the well-known name
 302                   this connection should hold a policy for.
 303                   A connection can not be an activator and a policy holder at
 304                   the same time time, so this bit is not allowed together with
 305                   <constant>KDBUS_HELLO_ACTIVATOR</constant>.
 306                 </para>
 307               </listitem>
 308             </varlistentry>
 309
 310             <varlistentry>
 311               <term><constant>KDBUS_HELLO_MONITOR</constant></term>
 312               <listitem>
 313                 <para>
 314                   Make this connection a monitor connection (see above).
 315                 </para>
 316                 <para>
 317                   This flag can only be set by privileged bus connections. See
 318                   below for more information.
 319                   A connection can not be monitor and an activator or a policy
 320                   holder at the same time time, so this bit is not allowed
 321                   together with <constant>KDBUS_HELLO_ACTIVATOR</constant> or
 322                   <constant>KDBUS_HELLO_POLICY_HOLDER</constant>.
 323                 </para>
 324               </listitem>
 325             </varlistentry>
 326
 327             <varlistentry>
 328               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 329               <listitem>
 330                 <para>
 331                   Requests a set of valid flags for this ioctl. When this bit is
 332                   set, no action is taken; the ioctl will return
 333                   <errorcode>0</errorcode>, and the <varname>flags</varname>
 334                   field will have all bits set that are valid for this command.
 335                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 336                   cleared by the operation.
 337                 </para>
 338               </listitem>
 339             </varlistentry>
 340           </variablelist>
 341         </listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term><varname>return_flags</varname></term>
 346         <listitem><para>
 347           Flags returned by the kernel. Currently unused and always set to
 348           <constant>0</constant> by the kernel.
 349         </para></listitem>
 350       </varlistentry>
 351
 352       <varlistentry>
 353         <term><varname>attach_flags_send</varname></term>
 354         <listitem><para>
 355           Set the bits for metadata this connection permits to be sent to the
 356           receiving peer. Only metadata items that are both allowed to be sent
 357           by the sender and that are requested by the receiver will be attached
 358           to the message. Note, however, that the bus may optionally require
 359           some of those bits to be set. If the match fails, the ioctl will fail
 360           with <varname>errno</varname> set to
 361           <constant>ECONNREFUSED</constant>. In either case, when returning the
 362           field will be set to the mask of metadata items that are enforced by
 363           the bus with the <constant>KDBUS_FLAGS_KERNEL</constant> bit set as
 364           well.
 365         </para></listitem>
 366       </varlistentry>
 367
 368       <varlistentry>
 369         <term><varname>attach_flags_recv</varname></term>
 370         <listitem><para>
 371           Request the attachment of metadata for each message received by this
 372           connection. See
 373           <citerefentry>
 374             <refentrytitle>kdbus</refentrytitle>
 375             <manvolnum>7</manvolnum>
 376           </citerefentry>
 377           for information about metadata, and
 378           <citerefentry>
 379             <refentrytitle>kdbus.item</refentrytitle>
 380             <manvolnum>7</manvolnum>
 381           </citerefentry>
 382           regarding items in general.
 383         </para></listitem>
 384       </varlistentry>
 385
 386       <varlistentry>
 387         <term><varname>bus_flags</varname></term>
 388         <listitem><para>
 389           Upon successful completion of the ioctl, this member will contain the
 390           flags of the bus it connected to.
 391         </para></listitem>
 392       </varlistentry>
 393
 394       <varlistentry>
 395         <term><varname>id</varname></term>
 396         <listitem><para>
 397           Upon successful completion of the command, this member will contain
 398           the numerical ID of the new connection.
 399         </para></listitem>
 400       </varlistentry>
 401
 402       <varlistentry>
 403         <term><varname>pool_size</varname></term>
 404         <listitem><para>
 405           The size of the communication pool, in bytes. The pool can be
 406           accessed by calling
 407           <citerefentry>
 408             <refentrytitle>mmap</refentrytitle>
 409             <manvolnum>2</manvolnum>
 410           </citerefentry>
 411           on the file descriptor that was used to issue the
 412           <constant>KDBUS_CMD_HELLO</constant> ioctl.
 413           The pool size of a connection must be greater than
 414           <constant>0</constant> and a multiple of
 415           <constant>PAGE_SIZE</constant>. See
 416           <citerefentry>
 417             <refentrytitle>kdbus.pool</refentrytitle>
 418             <manvolnum>7</manvolnum>
 419           </citerefentry>
 420           for more information.
 421         </para></listitem>
 422       </varlistentry>
 423
 424       <varlistentry>
 425         <term><varname>offset</varname></term>
 426         <listitem><para>
 427           The kernel will return the offset in the pool where returned details
 428           will be stored. See below.
 429         </para></listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term><varname>id128</varname></term>
 434         <listitem><para>
 435           Upon successful completion of the ioctl, this member will contain the
 436           <emphasis>128-bit UUID</emphasis> of the connected bus.
 437         </para></listitem>
 438       </varlistentry>
 439
 440       <varlistentry>
 441         <term><varname>items</varname></term>
 442         <listitem>
 443           <para>
 444             Variable list of items containing optional additional information.
 445             The following items are currently expected/valid:
 446           </para>
 447           <variablelist>
 448             <varlistentry>
 449               <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
 450               <listitem>
 451                 <para>
 452                   Contains a string that describes this connection, so it can
 453                   be identified later.
 454                 </para>
 455               </listitem>
 456             </varlistentry>
 457
 458             <varlistentry>
 459               <term><constant>KDBUS_ITEM_NAME</constant></term>
 460               <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
 461               <listitem>
 462                 <para>
 463                   For activators and policy holders only, combinations of
 464                   these two items describe policy access entries. See
 465                   <citerefentry>
 466                     <refentrytitle>kdbus.policy</refentrytitle>
 467                     <manvolnum>7</manvolnum>
 468                   </citerefentry>
 469                   for further details.
 470                 </para>
 471               </listitem>
 472             </varlistentry>
 473
 474             <varlistentry>
 475               <term><constant>KDBUS_ITEM_CREDS</constant></term>
 476               <term><constant>KDBUS_ITEM_PIDS</constant></term>
 477               <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
 478               <listitem>
 479                 <para>
 480                   Privileged bus users may submit these types in order to
 481                   create connections with faked credentials. This information
 482                   will be returned when peer information is queried by
 483                   <constant>KDBUS_CMD_CONN_INFO</constant>. See below for more
 484                   information on retrieving information on connections.
 485                 </para>
 486               </listitem>
 487             </varlistentry>
 488
 489             <varlistentry>
 490               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 491               <listitem><para>
 492                 With this item, programs can <emphasis>probe</emphasis> the
 493                 kernel for known item types. See
 494                 <citerefentry>
 495                   <refentrytitle>kdbus.item</refentrytitle>
 496                   <manvolnum>7</manvolnum>
 497                 </citerefentry>
 498                 for more details.
 499               </para></listitem>
 500             </varlistentry>
 501           </variablelist>
 502
 503           <para>
 504             Unrecognized items are rejected, and the ioctl will fail with
 505             <varname>errno</varname> set to <constant>EINVAL</constant>.
 506           </para>
 507         </listitem>
 508       </varlistentry>
 509     </variablelist>
 510
 511     <para>
 512       At the offset returned in the <varname>offset</varname> field of
 513       <type>struct kdbus_cmd_hello</type>, the kernel will store items
 514       of the following types:
 515     </para>
 516
 517     <variablelist>
 518       <varlistentry>
 519         <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
 520         <listitem>
 521           <para>
 522             Bloom filter parameter as defined by the bus creator.
 523           </para>
 524         </listitem>
 525       </varlistentry>
 526     </variablelist>
 527
 528     <para>
 529       The offset in the pool has to be freed with the
 530       <constant>KDBUS_CMD_FREE</constant> ioctl. See
 531       <citerefentry>
 532         <refentrytitle>kdbus.pool</refentrytitle>
 533         <manvolnum>7</manvolnum>
 534       </citerefentry>
 535       for further information.
 536     </para>
 537   </refsect1>
 538
 539   <refsect1>
 540     <title>Retrieving information on a connection</title>
 541     <para>
 542       The <constant>KDBUS_CMD_CONN_INFO</constant> ioctl can be used to
 543       retrieve credentials and properties of the initial creator of a
 544       connection. This ioctl uses the following struct.
 545     </para>
 546
 547     <programlisting>
 548 struct kdbus_cmd_info {
 549   __u64 size;
 550   __u64 flags;
 551   __u64 return_flags;
 552   __u64 id;
 553   __u64 attach_flags;
 554   __u64 offset;
 555   __u64 info_size;
 556   struct kdbus_item items[0];
 557 };
 558     </programlisting>
 559
 560     <variablelist>
 561       <varlistentry>
 562         <term><varname>size</varname></term>
 563         <listitem><para>
 564           The overall size of the struct, including its items.
 565         </para></listitem>
 566       </varlistentry>
 567
 568       <varlistentry>
 569         <term><varname>flags</varname></term>
 570         <listitem><para>
 571           Currently, no flags are supported.
 572           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 573           valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
 574           and the <varname>flags</varname> field is set to
 575           <constant>0</constant>.
 576         </para></listitem>
 577       </varlistentry>
 578
 579       <varlistentry>
 580         <term><varname>return_flags</varname></term>
 581         <listitem><para>
 582           Flags returned by the kernel. Currently unused and always set to
 583           <constant>0</constant> by the kernel.
 584         </para></listitem>
 585       </varlistentry>
 586
 587       <varlistentry>
 588         <term><varname>id</varname></term>
 589         <listitem><para>
 590           The numerical ID of the connection for which information is to be
 591           retrieved. If set to a non-zero value, the
 592           <constant>KDBUS_ITEM_OWNED_NAME</constant> item is ignored.
 593         </para></listitem>
 594       </varlistentry>
 595
 596       <varlistentry>
 597         <term><varname>attach_flags</varname></term>
 598         <listitem><para>
 599           Specifies which metadata items should be attached to the answer. See
 600           <citerefentry>
 601             <refentrytitle>kdbus.message</refentrytitle>
 602             <manvolnum>7</manvolnum>
 603           </citerefentry>.
 604         </para></listitem>
 605       </varlistentry>
 606
 607       <varlistentry>
 608         <term><varname>offset</varname></term>
 609         <listitem><para>
 610           When the ioctl returns, this field will contain the offset of the
 611           connection information inside the caller's pool. See
 612           <citerefentry>
 613             <refentrytitle>kdbus.pool</refentrytitle>
 614             <manvolnum>7</manvolnum>
 615           </citerefentry>
 616           for further information.
 617         </para></listitem>
 618       </varlistentry>
 619
 620       <varlistentry>
 621         <term><varname>info_size</varname></term>
 622         <listitem><para>
 623           The kernel will return the size of the returned information, so
 624           applications can optionally
 625           <citerefentry>
 626             <refentrytitle>mmap</refentrytitle>
 627             <manvolnum>2</manvolnum>
 628           </citerefentry>
 629           specific parts of the pool. See
 630           <citerefentry>
 631             <refentrytitle>kdbus.pool</refentrytitle>
 632             <manvolnum>7</manvolnum>
 633           </citerefentry>
 634           for further information.
 635         </para></listitem>
 636       </varlistentry>
 637
 638       <varlistentry>
 639         <term><varname>items</varname></term>
 640         <listitem>
 641           <para>
 642             The following items are expected for
 643             <constant>KDBUS_CMD_CONN_INFO</constant>.
 644           </para>
 645           <variablelist>
 646             <varlistentry>
 647               <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
 648               <listitem>
 649                 <para>
 650                   Contains the well-known name of the connection to look up as.
 651                   This item is mandatory if the <varname>id</varname> field is
 652                   set to 0.
 653                 </para>
 654               </listitem>
 655             </varlistentry>
 656
 657             <varlistentry>
 658               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 659               <listitem><para>
 660                 With this item, programs can <emphasis>probe</emphasis> the
 661                 kernel for known item types. See
 662                 <citerefentry>
 663                   <refentrytitle>kdbus.item</refentrytitle>
 664                   <manvolnum>7</manvolnum>
 665                 </citerefentry>
 666                 for more details.
 667               </para></listitem>
 668             </varlistentry>
 669           </variablelist>
 670           <para>
 671             Unrecognized items are rejected, and the ioctl will fail with
 672             <varname>errno</varname> set to <constant>EINVAL</constant>.
 673           </para>
 674         </listitem>
 675       </varlistentry>
 676     </variablelist>
 677
 678     <para>
 679       When the ioctl returns, the following struct will be stored in the
 680       caller's pool at <varname>offset</varname>. The fields in this struct
 681       are described below.
 682     </para>
 683
 684     <programlisting>
 685 struct kdbus_info {
 686   __u64 size;
 687   __u64 id;
 688   __u64 flags;
 689   struct kdbus_item items[0];
 690 };
 691     </programlisting>
 692
 693     <variablelist>
 694       <varlistentry>
 695         <term><varname>size</varname></term>
 696         <listitem><para>
 697           The overall size of the struct, including its items.
 698         </para></listitem>
 699       </varlistentry>
 700
 701       <varlistentry>
 702         <term><varname>id</varname></term>
 703         <listitem><para>
 704           The connection's unique ID.
 705         </para></listitem>
 706       </varlistentry>
 707
 708       <varlistentry>
 709         <term><varname>flags</varname></term>
 710         <listitem><para>
 711           The connection's flags as specified when it was created.
 712         </para></listitem>
 713       </varlistentry>
 714
 715       <varlistentry>
 716         <term><varname>items</varname></term>
 717         <listitem>
 718           <para>
 719             Depending on the <varname>flags</varname> field in
 720             <type>struct kdbus_cmd_info</type>, items of types
 721             <constant>KDBUS_ITEM_OWNED_NAME</constant> and
 722             <constant>KDBUS_ITEM_CONN_DESCRIPTION</constant> may follow here.
 723             <constant>KDBUS_ITEM_NEGOTIATE</constant> is also allowed.
 724           </para>
 725         </listitem>
 726       </varlistentry>
 727     </variablelist>
 728
 729     <para>
 730       Once the caller is finished with parsing the return buffer, it needs to
 731       employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
 732       order to free the buffer part. See
 733       <citerefentry>
 734         <refentrytitle>kdbus.pool</refentrytitle>
 735         <manvolnum>7</manvolnum>
 736       </citerefentry>
 737       for further information.
 738     </para>
 739   </refsect1>
 740
 741   <refsect1>
 742     <title>Getting information about a connection's bus creator</title>
 743     <para>
 744       The <constant>KDBUS_CMD_BUS_CREATOR_INFO</constant> ioctl takes the same
 745       struct as <constant>KDBUS_CMD_CONN_INFO</constant>, but is used to
 746       retrieve information about the creator of the bus the connection is
 747       attached to. The metadata returned by this call is collected during the
 748       creation of the bus and is never altered afterwards, so it provides
 749       pristine information on the task that created the bus, at the moment when
 750       it did so.
 751     </para>
 752     <para>
 753       In response to this call, a slice in the connection's pool is allocated
 754       and filled with an object of type <type>struct kdbus_info</type>,
 755       pointed to by the ioctl's <varname>offset</varname> field.
 756     </para>
 757
 758     <programlisting>
 759 struct kdbus_info {
 760   __u64 size;
 761   __u64 id;
 762   __u64 flags;
 763   struct kdbus_item items[0];
 764 };
 765     </programlisting>
 766
 767     <variablelist>
 768       <varlistentry>
 769         <term><varname>size</varname></term>
 770         <listitem><para>
 771           The overall size of the struct, including its items.
 772         </para></listitem>
 773       </varlistentry>
 774
 775       <varlistentry>
 776         <term><varname>id</varname></term>
 777         <listitem><para>
 778           The bus ID.
 779         </para></listitem>
 780       </varlistentry>
 781
 782       <varlistentry>
 783         <term><varname>flags</varname></term>
 784         <listitem><para>
 785           The bus flags as specified when it was created.
 786         </para></listitem>
 787       </varlistentry>
 788
 789       <varlistentry>
 790         <term><varname>items</varname></term>
 791         <listitem>
 792           <para>
 793             Metadata information is stored in items here. The item list
 794             contains a <constant>KDBUS_ITEM_MAKE_NAME</constant> item that
 795             indicates the bus name of the calling connection.
 796             <constant>KDBUS_ITEM_NEGOTIATE</constant> is allowed to probe
 797             for known item types.
 798           </para>
 799         </listitem>
 800       </varlistentry>
 801     </variablelist>
 802
 803     <para>
 804       Once the caller is finished with parsing the return buffer, it needs to
 805       employ the <constant>KDBUS_CMD_FREE</constant> command for the offset, in
 806       order to free the buffer part. See
 807       <citerefentry>
 808         <refentrytitle>kdbus.pool</refentrytitle>
 809         <manvolnum>7</manvolnum>
 810       </citerefentry>
 811       for further information.
 812     </para>
 813   </refsect1>
 814
 815   <refsect1>
 816     <title>Updating connection details</title>
 817     <para>
 818       Some of a connection's details can be updated with the
 819       <constant>KDBUS_CMD_CONN_UPDATE</constant> ioctl, using the file
 820       descriptor that was used to create the connection. The update command
 821       uses the following struct.
 822     </para>
 823
 824     <programlisting>
 825 struct kdbus_cmd {
 826   __u64 size;
 827   __u64 flags;
 828   __u64 return_flags;
 829   struct kdbus_item items[0];
 830 };
 831     </programlisting>
 832
 833     <variablelist>
 834       <varlistentry>
 835         <term><varname>size</varname></term>
 836         <listitem><para>
 837           The overall size of the struct, including its items.
 838         </para></listitem>
 839       </varlistentry>
 840
 841       <varlistentry>
 842         <term><varname>flags</varname></term>
 843         <listitem><para>
 844           Currently, no flags are supported.
 845           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 846           valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
 847           and the <varname>flags</varname> field is set to
 848           <constant>0</constant>.
 849         </para></listitem>
 850       </varlistentry>
 851
 852       <varlistentry>
 853         <term><varname>return_flags</varname></term>
 854         <listitem><para>
 855           Flags returned by the kernel. Currently unused and always set to
 856           <constant>0</constant> by the kernel.
 857         </para></listitem>
 858       </varlistentry>
 859
 860       <varlistentry>
 861         <term><varname>items</varname></term>
 862         <listitem>
 863           <para>
 864             Items to describe the connection details to be updated. The
 865             following item types are supported.
 866           </para>
 867           <variablelist>
 868             <varlistentry>
 869               <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
 870               <listitem>
 871                 <para>
 872                   Supply a new set of metadata items that this connection
 873                   permits to be sent along with messages.
 874                 </para>
 875               </listitem>
 876             </varlistentry>
 877
 878             <varlistentry>
 879               <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
 880               <listitem>
 881                 <para>
 882                   Supply a new set of metadata items that this connection
 883                   requests to be attached to each message.
 884                 </para>
 885               </listitem>
 886             </varlistentry>
 887
 888             <varlistentry>
 889               <term><constant>KDBUS_ITEM_NAME</constant></term>
 890               <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
 891               <listitem>
 892                 <para>
 893                   Policy holder connections may supply a new set of policy
 894                   information with these items. For other connection types,
 895                   <constant>EOPNOTSUPP</constant> is returned in
 896                   <varname>errno</varname>.
 897                 </para>
 898               </listitem>
 899             </varlistentry>
 900
 901             <varlistentry>
 902               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 903               <listitem><para>
 904                 With this item, programs can <emphasis>probe</emphasis> the
 905                 kernel for known item types. See
 906                 <citerefentry>
 907                   <refentrytitle>kdbus.item</refentrytitle>
 908                   <manvolnum>7</manvolnum>
 909                 </citerefentry>
 910                 for more details.
 911               </para></listitem>
 912             </varlistentry>
 913           </variablelist>
 914
 915           <para>
 916             Unrecognized items are rejected, and the ioctl will fail with
 917             <varname>errno</varname> set to <constant>EINVAL</constant>.
 918           </para>
 919         </listitem>
 920       </varlistentry>
 921     </variablelist>
 922   </refsect1>
 923
 924   <refsect1>
 925     <title>Termination of connections</title>
 926     <para>
 927       A connection can be terminated by simply calling
 928       <citerefentry>
 929         <refentrytitle>close</refentrytitle>
 930         <manvolnum>2</manvolnum>
 931       </citerefentry>
 932       on its file descriptor. All pending incoming messages will be discarded,
 933       and the memory allocated by the pool will be freed.
 934     </para>
 935
 936     <para>
 937       An alternative way of closing down a connection is via the
 938       <constant>KDBUS_CMD_BYEBYE</constant> ioctl. This ioctl will succeed only
 939       if the message queue of the connection is empty at the time of closing;
 940       otherwise, the ioctl will fail with <varname>errno</varname> set to
 941       <constant>EBUSY</constant>. When this ioctl returns
 942       successfully, the connection has been terminated and won't accept any new
 943       messages from remote peers. This way, a connection can be terminated
 944       race-free, without losing any messages. The ioctl takes an argument of
 945       type <type>struct kdbus_cmd</type>.
 946     </para>
 947
 948     <programlisting>
 949 struct kdbus_cmd {
 950   __u64 size;
 951   __u64 flags;
 952   __u64 return_flags;
 953   struct kdbus_item items[0];
 954 };
 955     </programlisting>
 956
 957     <variablelist>
 958       <varlistentry>
 959         <term><varname>size</varname></term>
 960         <listitem><para>
 961           The overall size of the struct, including its items.
 962         </para></listitem>
 963       </varlistentry>
 964
 965       <varlistentry>
 966         <term><varname>flags</varname></term>
 967         <listitem><para>
 968           Currently, no flags are supported.
 969           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 970           valid flags. If set, the ioctl will fail with
 971           <varname>errno</varname> set to <constant>EPROTO</constant>, and
 972           the <varname>flags</varname> field is set to <constant>0</constant>.
 973         </para></listitem>
 974       </varlistentry>
 975
 976       <varlistentry>
 977         <term><varname>return_flags</varname></term>
 978         <listitem><para>
 979           Flags returned by the kernel. Currently unused and always set to
 980           <constant>0</constant> by the kernel.
 981         </para></listitem>
 982       </varlistentry>
 983
 984       <varlistentry>
 985         <term><varname>items</varname></term>
 986         <listitem>
 987           <para>
 988             The following item types are supported.
 989           </para>
 990           <variablelist>
 991             <varlistentry>
 992               <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 993               <listitem><para>
 994                 With this item, programs can <emphasis>probe</emphasis> the
 995                 kernel for known item types. See
 996                 <citerefentry>
 997                   <refentrytitle>kdbus.item</refentrytitle>
 998                   <manvolnum>7</manvolnum>
 999                 </citerefentry>
1000                 for more details.
1001               </para></listitem>
1002             </varlistentry>
1003           </variablelist>
1004
1005           <para>
1006             Unrecognized items are rejected, and the ioctl will fail with
1007             <varname>errno</varname> set to <constant>EINVAL</constant>.
1008           </para>
1009         </listitem>
1010       </varlistentry>
1011     </variablelist>
1012   </refsect1>
1013
1014   <refsect1>
1015     <title>Return value</title>
1016     <para>
1017       On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
1018       on error, <errorcode>-1</errorcode> is returned, and
1019       <varname>errno</varname> is set to indicate the error.
1020       If the issued ioctl is illegal for the file descriptor used,
1021       <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
1022     </para>
1023
1024     <refsect2>
1025       <title>
1026         <constant>KDBUS_CMD_HELLO</constant> may fail with the following
1027         errors
1028       </title>
1029
1030       <variablelist>
1031         <varlistentry>
1032           <term><constant>EFAULT</constant></term>
1033           <listitem><para>
1034             The supplied pool size was 0 or not a multiple of the page size.
1035           </para></listitem>
1036         </varlistentry>
1037
1038         <varlistentry>
1039           <term><constant>EINVAL</constant></term>
1040           <listitem><para>
1041             The flags supplied in <type>struct kdbus_cmd_hello</type>
1042             are invalid.
1043           </para></listitem>
1044         </varlistentry>
1045
1046         <varlistentry>
1047           <term><constant>EINVAL</constant></term>
1048           <listitem><para>
1049             An illegal combination of
1050             <constant>KDBUS_HELLO_MONITOR</constant>,
1051             <constant>KDBUS_HELLO_ACTIVATOR</constant> and
1052             <constant>KDBUS_HELLO_POLICY_HOLDER</constant> was passed in
1053             <varname>flags</varname>.
1054           </para></listitem>
1055         </varlistentry>
1056
1057         <varlistentry>
1058           <term><constant>EINVAL</constant></term>
1059           <listitem><para>
1060             An invalid set of items was supplied.
1061           </para></listitem>
1062         </varlistentry>
1063
1064         <varlistentry>
1065           <term><constant>ECONNREFUSED</constant></term>
1066           <listitem><para>
1067             The attach_flags_send field did not satisfy the requirements of
1068             the bus.
1069           </para></listitem>
1070         </varlistentry>
1071
1072         <varlistentry>
1073           <term><constant>EPERM</constant></term>
1074           <listitem><para>
1075             A <constant>KDBUS_ITEM_CREDS</constant> items was supplied, but the
1076             current user is not privileged.
1077           </para></listitem>
1078         </varlistentry>
1079
1080         <varlistentry>
1081           <term><constant>ESHUTDOWN</constant></term>
1082           <listitem><para>
1083             The bus you were trying to connect to has already been shut down.
1084           </para></listitem>
1085         </varlistentry>
1086
1087         <varlistentry>
1088           <term><constant>EMFILE</constant></term>
1089           <listitem><para>
1090             The maximum number of connections on the bus has been reached.
1091           </para></listitem>
1092         </varlistentry>
1093
1094         <varlistentry>
1095           <term><constant>EOPNOTSUPP</constant></term>
1096           <listitem><para>
1097             The endpoint does not support the connection flags supplied in
1098             <type>struct kdbus_cmd_hello</type>.
1099           </para></listitem>
1100         </varlistentry>
1101       </variablelist>
1102     </refsect2>
1103
1104     <refsect2>
1105       <title>
1106         <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following
1107         errors
1108       </title>
1109
1110       <variablelist>
1111         <varlistentry>
1112           <term><constant>EALREADY</constant></term>
1113           <listitem><para>
1114             The connection has already been shut down.
1115           </para></listitem>
1116         </varlistentry>
1117
1118         <varlistentry>
1119           <term><constant>EBUSY</constant></term>
1120           <listitem><para>
1121             There are still messages queued up in the connection's pool.
1122           </para></listitem>
1123         </varlistentry>
1124       </variablelist>
1125     </refsect2>
1126
1127     <refsect2>
1128       <title>
1129         <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following
1130         errors
1131       </title>
1132
1133       <variablelist>
1134         <varlistentry>
1135           <term><constant>EINVAL</constant></term>
1136           <listitem><para>
1137             Invalid flags, or neither an ID nor a name was provided, or the
1138             name is invalid.
1139           </para></listitem>
1140         </varlistentry>
1141
1142         <varlistentry>
1143           <term><constant>ESRCH</constant></term>
1144           <listitem><para>
1145             Connection lookup by name failed.
1146           </para></listitem>
1147         </varlistentry>
1148
1149         <varlistentry>
1150           <term><constant>ENXIO</constant></term>
1151           <listitem><para>
1152             No connection with the provided connection ID found.
1153           </para></listitem>
1154         </varlistentry>
1155       </variablelist>
1156     </refsect2>
1157
1158     <refsect2>
1159       <title>
1160         <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following
1161         errors
1162       </title>
1163
1164       <variablelist>
1165         <varlistentry>
1166           <term><constant>EINVAL</constant></term>
1167           <listitem><para>
1168             Illegal flags or items.
1169           </para></listitem>
1170         </varlistentry>
1171
1172         <varlistentry>
1173           <term><constant>EINVAL</constant></term>
1174           <listitem><para>
1175             Wildcards submitted in policy entries, or illegal sequence
1176             of policy items.
1177           </para></listitem>
1178         </varlistentry>
1179
1180         <varlistentry>
1181           <term><constant>EOPNOTSUPP</constant></term>
1182           <listitem><para>
1183             Operation not supported by connection.
1184           </para></listitem>
1185         </varlistentry>
1186
1187         <varlistentry>
1188           <term><constant>E2BIG</constant></term>
1189           <listitem><para>
1190             Too many policy items attached.
1191           </para></listitem>
1192         </varlistentry>
1193       </variablelist>
1194     </refsect2>
1195   </refsect1>
1196
1197   <refsect1>
1198     <title>See Also</title>
1199     <simplelist type="inline">
1200       <member>
1201         <citerefentry>
1202           <refentrytitle>kdbus</refentrytitle>
1203           <manvolnum>7</manvolnum>
1204         </citerefentry>
1205       </member>
1206       <member>
1207         <citerefentry>
1208           <refentrytitle>kdbus.bus</refentrytitle>
1209           <manvolnum>7</manvolnum>
1210         </citerefentry>
1211       </member>
1212       <member>
1213         <citerefentry>
1214           <refentrytitle>kdbus.endpoint</refentrytitle>
1215           <manvolnum>7</manvolnum>
1216         </citerefentry>
1217       </member>
1218       <member>
1219         <citerefentry>
1220           <refentrytitle>kdbus.message</refentrytitle>
1221           <manvolnum>7</manvolnum>
1222         </citerefentry>
1223       </member>
1224       <member>
1225         <citerefentry>
1226           <refentrytitle>kdbus.name</refentrytitle>
1227           <manvolnum>7</manvolnum>
1228         </citerefentry>
1229       </member>
1230       <member>
1231         <citerefentry>
1232           <refentrytitle>kdbus.policy</refentrytitle>
1233           <manvolnum>7</manvolnum>
1234         </citerefentry>
1235       </member>
1236       <member>
1237         <citerefentry>
1238           <refentrytitle>kdbus.pool</refentrytitle>
1239           <manvolnum>7</manvolnum>
1240         </citerefentry>
1241       </member>
1242       <member>
1243         <citerefentry>
1244           <refentrytitle>kdbus.item</refentrytitle>
1245           <manvolnum>7</manvolnum>
1246         </citerefentry>
1247       </member>
1248     </simplelist>
1249   </refsect1>
1250 </refentry>