ipc/kdbus/Documentation/kdbus.name.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.name">
   6
   7   <refentryinfo>
   8     <title>kdbus.name</title>
   9     <productname>kdbus.name</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.name</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.name</refname>
  19     <refpurpose>kdbus.name</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24     <para>
  25       Each
  26       <citerefentry>
  27         <refentrytitle>kdbus.bus</refentrytitle>
  28         <manvolnum>7</manvolnum>
  29       </citerefentry>
  30       instantiates a name registry to resolve well-known names into unique
  31       connection IDs for message delivery. The registry will be queried when a
  32       message is sent with <varname>kdbus_msg.dst_id</varname> set to
  33       <constant>KDBUS_DST_ID_NAME</constant>, or when a registry dump is
  34       requested with <constant>KDBUS_CMD_NAME_LIST</constant>.
  35     </para>
  36
  37     <para>
  38       All of the below is subject to policy rules for <emphasis>SEE</emphasis>
  39       and <emphasis>OWN</emphasis> permissions. See
  40       <citerefentry>
  41         <refentrytitle>kdbus.policy</refentrytitle>
  42         <manvolnum>7</manvolnum>
  43       </citerefentry>
  44       for more information.
  45     </para>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Name validity</title>
  50     <para>
  51       A name has to comply with the following rules in order to be considered
  52       valid.
  53     </para>
  54
  55     <itemizedlist>
  56       <listitem>
  57         <para>
  58           The name has two or more elements separated by a
  59           '<literal>.</literal>' (period) character.
  60         </para>
  61       </listitem>
  62       <listitem>
  63         <para>
  64           All elements must contain at least one character.
  65         </para>
  66       </listitem>
  67       <listitem>
  68         <para>
  69           Each element must only contain the ASCII characters
  70           <literal>[A-Z][a-z][0-9]_</literal> and must not begin with a
  71           digit.
  72         </para>
  73       </listitem>
  74       <listitem>
  75         <para>
  76           The name must contain at least one '<literal>.</literal>' (period)
  77           character (and thus at least two elements).
  78         </para>
  79       </listitem>
  80       <listitem>
  81         <para>
  82           The name must not begin with a '<literal>.</literal>' (period)
  83           character.
  84         </para>
  85       </listitem>
  86       <listitem>
  87         <para>
  88           The name must not exceed <constant>255</constant> characters in
  89           length.
  90         </para>
  91       </listitem>
  92     </itemizedlist>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Acquiring a name</title>
  97     <para>
  98       To acquire a name, a client uses the
  99       <constant>KDBUS_CMD_NAME_ACQUIRE</constant> ioctl with
 100       <type>struct kdbus_cmd</type> as argument.
 101     </para>
 102
 103     <programlisting>
 104 struct kdbus_cmd {
 105   __u64 size;
 106   __u64 flags;
 107   __u64 return_flags;
 108   struct kdbus_item items[0];
 109 };
 110     </programlisting>
 111
 112     <para>The fields in this struct are described below.</para>
 113
 114     <variablelist>
 115       <varlistentry>
 116         <term><varname>size</varname></term>
 117         <listitem><para>
 118           The overall size of the struct, including its items.
 119         </para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><varname>flags</varname></term>
 124         <listitem><para>Flags to control details in the name acquisition.</para>
 125           <variablelist>
 126             <varlistentry>
 127               <term><constant>KDBUS_NAME_REPLACE_EXISTING</constant></term>
 128               <listitem>
 129                 <para>
 130                   Acquiring a name that is already present usually fails,
 131                   unless this flag is set in the call, and
 132                   <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> (see below)
 133                   was set when the current owner of the name acquired it, or
 134                   if the current owner is an activator connection (see
 135                   <citerefentry>
 136                     <refentrytitle>kdbus.connection</refentrytitle>
 137                     <manvolnum>7</manvolnum>
 138                   </citerefentry>).
 139                 </para>
 140               </listitem>
 141             </varlistentry>
 142
 143             <varlistentry>
 144               <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
 145               <listitem>
 146                 <para>
 147                   Allow other connections to take over this name. When this
 148                   happens, the former owner of the connection will be notified
 149                   of the name loss.
 150                 </para>
 151               </listitem>
 152             </varlistentry>
 153
 154             <varlistentry>
 155               <term><constant>KDBUS_NAME_QUEUE</constant></term>
 156               <listitem>
 157                 <para>
 158                   A name that is already acquired by a connection can not be
 159                   acquired again (unless the
 160                   <constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant> flag was
 161                   set during acquisition; see above).
 162                   However, a connection can put itself in a queue of
 163                   connections waiting for the name to be released. Once that
 164                   happens, the first connection in that queue becomes the new
 165                   owner and is notified accordingly.
 166                 </para>
 167               </listitem>
 168             </varlistentry>
 169
 170             <varlistentry>
 171               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 172               <listitem>
 173                 <para>
 174                   Request a set of valid flags for this ioctl. When this bit is
 175                   set, no action is taken; the ioctl will fail with
 176                   <errorcode>-1</errorcode>, and <varname>errno</varname>
 177                   is set to <constant>EPROTO</constant>.
 178                   Once the ioctl returned, the <varname>flags</varname>
 179                   field will have all bits set that the kernel recognizes as
 180                   valid for this command.
 181                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 182                   cleared by the operation.
 183                 </para>
 184               </listitem>
 185             </varlistentry>
 186           </variablelist>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><varname>return_flags</varname></term>
 192         <listitem>
 193           <para>
 194             Flags returned by the kernel. Currently, the following may be
 195             returned by the kernel.
 196           </para>
 197           <variablelist>
 198             <varlistentry>
 199               <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
 200               <listitem>
 201                 <para>
 202                   The name was not acquired yet, but the connection was
 203                   placed in the queue of peers waiting for the name.
 204                   This can only happen if <constant>KDBUS_NAME_QUEUE</constant>
 205                   was set in the <varname>flags</varname> member (see above).
 206                   The connection will receive a name owner change notification
 207                   once the current owner has given up the name and its
 208                   ownership was transferred.
 209                 </para>
 210               </listitem>
 211             </varlistentry>
 212           </variablelist>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><varname>items</varname></term>
 218         <listitem>
 219           <para>
 220             Items to submit the name. Currently, one item of type
 221             <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
 222             the contained string must be a valid bus name.
 223             <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
 224             valid item types. See
 225             <citerefentry>
 226               <refentrytitle>kdbus.item</refentrytitle>
 227               <manvolnum>7</manvolnum>
 228             </citerefentry>
 229             for a detailed description of how this item is used.
 230           </para>
 231           <para>
 232             Unrecognized items are rejected, and the ioctl will fail with
 233             <varname>errno</varname> set to <errorname>>EINVAL</errorname>.
 234           </para>
 235         </listitem>
 236       </varlistentry>
 237     </variablelist>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>Releasing a name</title>
 242     <para>
 243       A connection may release a name explicitly with the
 244       <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl. If the connection was
 245       an implementer of an activatable name, its pending messages are moved
 246       back to the activator. If there are any connections queued up as waiters
 247       for the name, the first one in the queue (the oldest entry) will become
 248       the new owner. The same happens implicitly for all names once a
 249       connection terminates. See
 250       <citerefentry>
 251         <refentrytitle>kdbus.connection</refentrytitle>
 252         <manvolnum>7</manvolnum>
 253       </citerefentry>
 254       for more information on connections.
 255     </para>
 256     <para>
 257       The <constant>KDBUS_CMD_NAME_RELEASE</constant> ioctl uses the same data
 258       structure as the acquisition call
 259       (<constant>KDBUS_CMD_NAME_ACQUIRE</constant>),
 260       but with slightly different field usage.
 261     </para>
 262
 263     <programlisting>
 264 struct kdbus_cmd {
 265   __u64 size;
 266   __u64 flags;
 267   __u64 return_flags;
 268   struct kdbus_item items[0];
 269 };
 270     </programlisting>
 271
 272     <para>The fields in this struct are described below.</para>
 273
 274     <variablelist>
 275       <varlistentry>
 276         <term><varname>size</varname></term>
 277         <listitem><para>
 278           The overall size of the struct, including its items.
 279         </para></listitem>
 280       </varlistentry>
 281
 282       <varlistentry>
 283         <term><varname>flags</varname></term>
 284         <listitem><para>
 285           Flags to the command. Currently unused.
 286           <constant>KDBUS_FLAG_NEGOTIATE</constant> is accepted to probe for
 287           valid flags. If set, the ioctl will return <errorcode>0</errorcode>,
 288           and the <varname>flags</varname> field is set to
 289           <constant>0</constant>.
 290         </para></listitem>
 291       </varlistentry>
 292
 293       <varlistentry>
 294         <term><varname>return_flags</varname></term>
 295         <listitem><para>
 296           Flags returned by the kernel. Currently unused and always set to
 297           <constant>0</constant> by the kernel.
 298         </para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><varname>items</varname></term>
 303         <listitem>
 304           <para>
 305             Items to submit the name. Currently, one item of type
 306             <constant>KDBUS_ITEM_NAME</constant> is expected and allowed, and
 307             the contained string must be a valid bus name.
 308             <constant>KDBUS_ITEM_NEGOTIATE</constant> may be used to probe for
 309             valid item types. See
 310             <citerefentry>
 311               <refentrytitle>kdbus.item</refentrytitle>
 312               <manvolnum>7</manvolnum>
 313             </citerefentry>
 314             for a detailed description of how this item is used.
 315           </para>
 316           <para>
 317             Unrecognized items are rejected, and the ioctl will fail with
 318             <varname>errno</varname> set to <constant>EINVAL</constant>.
 319           </para>
 320         </listitem>
 321       </varlistentry>
 322     </variablelist>
 323   </refsect1>
 324
 325   <refsect1>
 326     <title>Dumping the name registry</title>
 327     <para>
 328       A connection may request a complete or filtered dump of currently active
 329       bus names with the <constant>KDBUS_CMD_LIST</constant> ioctl, which
 330       takes a <type>struct kdbus_cmd_list</type> as argument.
 331     </para>
 332
 333     <programlisting>
 334 struct kdbus_cmd_list {
 335   __u64 flags;
 336   __u64 return_flags;
 337   __u64 offset;
 338 };
 339     </programlisting>
 340
 341     <para>The fields in this struct are described below.</para>
 342
 343     <variablelist>
 344       <varlistentry>
 345         <term><varname>flags</varname></term>
 346         <listitem>
 347           <para>
 348             Any combination of flags to specify which names should be dumped.
 349           </para>
 350           <variablelist>
 351             <varlistentry>
 352               <term><constant>KDBUS_LIST_UNIQUE</constant></term>
 353               <listitem>
 354                 <para>
 355                   List the unique (numeric) IDs of the connection, whether it
 356                   owns a name or not.
 357                 </para>
 358               </listitem>
 359             </varlistentry>
 360
 361             <varlistentry>
 362               <term><constant>KDBUS_LIST_NAMES</constant></term>
 363               <listitem>
 364                 <para>
 365                   List well-known names stored in the database which are
 366                   actively owned by a real connection (not an activator).
 367                 </para>
 368               </listitem>
 369             </varlistentry>
 370
 371             <varlistentry>
 372               <term><constant>KDBUS_LIST_ACTIVATORS</constant></term>
 373               <listitem>
 374                 <para>
 375                   List names that are owned by an activator.
 376                 </para>
 377               </listitem>
 378             </varlistentry>
 379
 380             <varlistentry>
 381               <term><constant>KDBUS_LIST_QUEUED</constant></term>
 382               <listitem>
 383                 <para>
 384                   List connections that are not yet owning a name but are
 385                   waiting for it to become available.
 386                 </para>
 387               </listitem>
 388             </varlistentry>
 389
 390             <varlistentry>
 391               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 392               <listitem>
 393                 <para>
 394                   Request a set of valid flags for this ioctl. When this bit is
 395                   set, no action is taken; the ioctl will fail with
 396                   <errorcode>-1</errorcode>, and <varname>errno</varname>
 397                   is set to <constant>EPROTO</constant>.
 398                   Once the ioctl returned, the <varname>flags</varname>
 399                   field will have all bits set that the kernel recognizes as
 400                   valid for this command.
 401                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 402                   cleared by the operation.
 403                 </para>
 404               </listitem>
 405             </varlistentry>
 406           </variablelist>
 407         </listitem>
 408       </varlistentry>
 409
 410       <varlistentry>
 411         <term><varname>return_flags</varname></term>
 412         <listitem><para>
 413           Flags returned by the kernel. Currently unused and always set to
 414           <constant>0</constant> by the kernel.
 415         </para></listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><varname>offset</varname></term>
 420         <listitem><para>
 421           When the ioctl returns successfully, the offset to the name registry
 422           dump inside the connection's pool will be stored in this field.
 423         </para></listitem>
 424       </varlistentry>
 425     </variablelist>
 426
 427     <para>
 428       The returned list of names is stored in a <type>struct kdbus_list</type>
 429       that in turn contains an array of type <type>struct kdbus_info</type>,
 430       The array-size in bytes is given as <varname>list_size</varname>.
 431       The fields inside <type>struct kdbus_info</type> is described next.
 432     </para>
 433
 434     <programlisting>
 435 struct kdbus_info {
 436   __u64 size;
 437   __u64 id;
 438   __u64 flags;
 439   struct kdbus_item items[0];
 440 };
 441     </programlisting>
 442
 443     <para>The fields in this struct are described below.</para>
 444
 445     <variablelist>
 446       <varlistentry>
 447         <term><varname>size</varname></term>
 448         <listitem><para>
 449           The overall size of the struct, including its items.
 450         </para></listitem>
 451       </varlistentry>
 452
 453       <varlistentry>
 454         <term><varname>id</varname></term>
 455         <listitem><para>
 456           The owning connection's unique ID.
 457         </para></listitem>
 458       </varlistentry>
 459
 460       <varlistentry>
 461         <term><varname>flags</varname></term>
 462         <listitem><para>
 463           The flags of the owning connection.
 464         </para></listitem>
 465       </varlistentry>
 466
 467       <varlistentry>
 468         <term><varname>items</varname></term>
 469         <listitem>
 470           <para>
 471             Items containing the actual name. Currently, one item of type
 472             <constant>KDBUS_ITEM_OWNED_NAME</constant> will be attached,
 473             including the name's flags. In that item, the flags field of the
 474             name may carry the following bits:
 475           </para>
 476           <variablelist>
 477             <varlistentry>
 478               <term><constant>KDBUS_NAME_ALLOW_REPLACEMENT</constant></term>
 479               <listitem>
 480                 <para>
 481                   Other connections are allowed to take over this name from the
 482                   connection that owns it.
 483                 </para>
 484               </listitem>
 485             </varlistentry>
 486
 487             <varlistentry>
 488               <term><constant>KDBUS_NAME_IN_QUEUE</constant></term>
 489               <listitem>
 490                 <para>
 491                   When retrieving a list of currently acquired names in the
 492                   registry, this flag indicates whether the connection
 493                   actually owns the name or is currently waiting for it to
 494                   become available.
 495                 </para>
 496               </listitem>
 497             </varlistentry>
 498
 499             <varlistentry>
 500               <term><constant>KDBUS_NAME_ACTIVATOR</constant></term>
 501               <listitem>
 502                 <para>
 503                   An activator connection owns a name as a placeholder for an
 504                   implementer, which is started on demand by programs as soon
 505                   as the first message arrives. There's some more information
 506                   on this topic in
 507                   <citerefentry>
 508                     <refentrytitle>kdbus.connection</refentrytitle>
 509                     <manvolnum>7</manvolnum>
 510                   </citerefentry>
 511                   .
 512                 </para>
 513                 <para>
 514                   In contrast to
 515                   <constant>KDBUS_NAME_REPLACE_EXISTING</constant>,
 516                   when a name is taken over from an activator connection, all
 517                   the messages that have been queued in the activator
 518                   connection will be moved over to the new owner. The activator
 519                   connection will still be tracked for the name and will take
 520                   control again if the implementer connection terminates.
 521                 </para>
 522                 <para>
 523                   This flag can not be used when acquiring a name, but is
 524                   implicitly set through <constant>KDBUS_CMD_HELLO</constant>
 525                   with <constant>KDBUS_HELLO_ACTIVATOR</constant> set in
 526                   <varname>kdbus_cmd_hello.conn_flags</varname>.
 527                 </para>
 528               </listitem>
 529             </varlistentry>
 530
 531             <varlistentry>
 532               <term><constant>KDBUS_FLAG_NEGOTIATE</constant></term>
 533               <listitem>
 534                 <para>
 535                   Requests a set of valid flags for this ioctl. When this bit is
 536                   set, no action is taken; the ioctl will return
 537                   <errorcode>0</errorcode>, and the <varname>flags</varname>
 538                   field will have all bits set that are valid for this command.
 539                   The <constant>KDBUS_FLAG_NEGOTIATE</constant> bit will be
 540                   cleared by the operation.
 541                 </para>
 542               </listitem>
 543             </varlistentry>
 544           </variablelist>
 545         </listitem>
 546       </varlistentry>
 547     </variablelist>
 548
 549     <para>
 550       The returned buffer must be freed with the
 551       <constant>KDBUS_CMD_FREE</constant> ioctl when the user is finished with
 552       it. See
 553       <citerefentry>
 554         <refentrytitle>kdbus.pool</refentrytitle>
 555         <manvolnum>7</manvolnum>
 556       </citerefentry>
 557       for more information.
 558     </para>
 559   </refsect1>
 560
 561   <refsect1>
 562     <title>Return value</title>
 563     <para>
 564       On success, all mentioned ioctl commands return <errorcode>0</errorcode>;
 565       on error, <errorcode>-1</errorcode> is returned, and
 566       <varname>errno</varname> is set to indicate the error.
 567       If the issued ioctl is illegal for the file descriptor used,
 568       <varname>errno</varname> will be set to <constant>ENOTTY</constant>.
 569     </para>
 570
 571     <refsect2>
 572       <title>
 573         <constant>KDBUS_CMD_NAME_ACQUIRE</constant> may fail with the following
 574         errors
 575       </title>
 576
 577       <variablelist>
 578         <varlistentry>
 579           <term><constant>EINVAL</constant></term>
 580           <listitem><para>
 581             Illegal command flags, illegal name provided, or an activator
 582             tried to acquire a second name.
 583           </para></listitem>
 584         </varlistentry>
 585
 586         <varlistentry>
 587           <term><constant>EPERM</constant></term>
 588           <listitem><para>
 589             Policy prohibited name ownership.
 590           </para></listitem>
 591         </varlistentry>
 592
 593         <varlistentry>
 594           <term><constant>EALREADY</constant></term>
 595           <listitem><para>
 596             Connection already owns that name.
 597           </para></listitem>
 598         </varlistentry>
 599
 600         <varlistentry>
 601           <term><constant>EEXIST</constant></term>
 602           <listitem><para>
 603             The name already exists and can not be taken over.
 604           </para></listitem>
 605         </varlistentry>
 606
 607         <varlistentry>
 608           <term><constant>E2BIG</constant></term>
 609           <listitem><para>
 610             The maximum number of well-known names per connection is exhausted.
 611           </para></listitem>
 612         </varlistentry>
 613       </variablelist>
 614     </refsect2>
 615
 616     <refsect2>
 617       <title>
 618         <constant>KDBUS_CMD_NAME_RELEASE</constant>
 619         may fail with the following errors
 620       </title>
 621
 622       <variablelist>
 623         <varlistentry>
 624           <term><constant>EINVAL</constant></term>
 625           <listitem><para>
 626             Invalid command flags, or invalid name provided.
 627           </para></listitem>
 628         </varlistentry>
 629
 630         <varlistentry>
 631           <term><constant>ESRCH</constant></term>
 632           <listitem><para>
 633             Name is not found in the registry.
 634           </para></listitem>
 635         </varlistentry>
 636
 637         <varlistentry>
 638           <term><constant>EADDRINUSE</constant></term>
 639           <listitem><para>
 640             Name is owned by a different connection and can't be released.
 641           </para></listitem>
 642         </varlistentry>
 643       </variablelist>
 644     </refsect2>
 645
 646     <refsect2>
 647       <title>
 648         <constant>KDBUS_CMD_LIST</constant> may fail with the following
 649         errors
 650       </title>
 651
 652       <variablelist>
 653         <varlistentry>
 654           <term><constant>EINVAL</constant></term>
 655           <listitem><para>
 656             Invalid command flags
 657           </para></listitem>
 658         </varlistentry>
 659
 660         <varlistentry>
 661           <term><constant>ENOBUFS</constant></term>
 662           <listitem><para>
 663             No available memory in the connection's pool.
 664           </para></listitem>
 665         </varlistentry>
 666       </variablelist>
 667     </refsect2>
 668   </refsect1>
 669
 670   <refsect1>
 671     <title>See Also</title>
 672     <simplelist type="inline">
 673       <member>
 674         <citerefentry>
 675           <refentrytitle>kdbus</refentrytitle>
 676           <manvolnum>7</manvolnum>
 677         </citerefentry>
 678       </member>
 679       <member>
 680         <citerefentry>
 681           <refentrytitle>kdbus.bus</refentrytitle>
 682           <manvolnum>7</manvolnum>
 683         </citerefentry>
 684       </member>
 685       <member>
 686         <citerefentry>
 687           <refentrytitle>kdbus.connection</refentrytitle>
 688           <manvolnum>7</manvolnum>
 689         </citerefentry>
 690       </member>
 691       <member>
 692         <citerefentry>
 693           <refentrytitle>kdbus.item</refentrytitle>
 694           <manvolnum>7</manvolnum>
 695         </citerefentry>
 696       </member>
 697       <member>
 698         <citerefentry>
 699           <refentrytitle>kdbus.policy</refentrytitle>
 700           <manvolnum>7</manvolnum>
 701         </citerefentry>
 702       </member>
 703       <member>
 704         <citerefentry>
 705           <refentrytitle>kdbus.pool</refentrytitle>
 706           <manvolnum>7</manvolnum>
 707         </citerefentry>
 708       </member>
 709     </simplelist>
 710   </refsect1>
 711 </refentry>