ipc/kdbus/Documentation/kdbus.item.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.item</title>
   9     <productname>kdbus item</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.item</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.item</refname>
  19     <refpurpose>kdbus item structure, layout and usage</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>
  26       To flexibly augment transport structures, data blobs of type
  27       <type>struct kdbus_item</type> can be attached to the structs passed
  28       into the ioctls. Some ioctls make items of certain types mandatory,
  29       others are optional. Items that are unsupported by ioctls they are
  30       attached to will cause the ioctl to fail with <varname>errno</varname>
  31       set to <constant>EINVAL</constant>.
  32       Items are also used for information stored in a connection's
  33       <emphasis>pool</emphasis>, such as received messages, name lists or
  34       requested connection or bus owner information. Depending on the type of
  35       an item, its total size is either fixed or variable.
  36     </para>
  37
  38     <refsect2>
  39       <title>Chaining items</title>
  40       <para>
  41         Whenever items are used as part of the kdbus kernel API, they are
  42         embedded in structs that are embedded inside structs that themselves
  43         include a size field containing the overall size of the structure.
  44         This allows multiple items to be chained up, and an item iterator
  45         (see below) is capable of detecting the end of an item chain.
  46       </para>
  47     </refsect2>
  48
  49     <refsect2>
  50       <title>Alignment</title>
  51       <para>
  52         The kernel expects all items to be aligned to 8-byte boundaries.
  53         Unaligned items will cause the ioctl they are used with to fail
  54         with <varname>errno</varname> set to <constant>EINVAL</constant>.
  55         An item that has an unaligned size itself hence needs to be padded
  56         if it is followed by another item.
  57       </para>
  58     </refsect2>
  59
  60     <refsect2>
  61       <title>Iterating items</title>
  62       <para>
  63         A simple iterator would iterate over the items until the items have
  64         reached the embedding structure's overall size. An example
  65         implementation is shown below.
  66       </para>
  67
  68       <programlisting><![CDATA[
  69 #define KDBUS_ALIGN8(val) (((val) + 7) & ~7)
  70
  71 #define KDBUS_ITEM_NEXT(item) \
  72     (typeof(item))(((uint8_t *)item) + KDBUS_ALIGN8((item)->size))
  73
  74 #define KDBUS_ITEM_FOREACH(item, head, first)                      \
  75     for (item = (head)->first;                                     \
  76          ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \
  77           ((uint8_t *)(item) >= (uint8_t *)(head));                \
  78          item = KDBUS_ITEM_NEXT(item))
  79       ]]></programlisting>
  80     </refsect2>
  81   </refsect1>
  82
  83   <refsect1>
  84     <title>Item layout</title>
  85     <para>
  86       A <type>struct kdbus_item</type> consists of a
  87       <varname>size</varname> field, describing its overall size, and a
  88       <varname>type</varname> field, both 64 bit wide. They are followed by
  89       a union to store information that is specific to the item's type.
  90       The struct layout is shown below.
  91     </para>
  92
  93     <programlisting>
  94 struct kdbus_item {
  95   __u64 size;
  96   __u64 type;
  97   /* item payload - see below */
  98   union {
  99     __u8 data[0];
 100     __u32 data32[0];
 101     __u64 data64[0];
 102     char str[0];
 103
 104     __u64 id;
 105     struct kdbus_vec vec;
 106     struct kdbus_creds creds;
 107     struct kdbus_pids pids;
 108     struct kdbus_audit audit;
 109     struct kdbus_caps caps;
 110     struct kdbus_timestamp timestamp;
 111     struct kdbus_name name;
 112     struct kdbus_bloom_parameter bloom_parameter;
 113     struct kdbus_bloom_filter bloom_filter;
 114     struct kdbus_memfd memfd;
 115     int fds[0];
 116     struct kdbus_notify_name_change name_change;
 117     struct kdbus_notify_id_change id_change;
 118     struct kdbus_policy_access policy_access;
 119   };
 120 };
 121     </programlisting>
 122
 123     <para>
 124       <type>struct kdbus_item</type> should never be used to allocate
 125       an item instance, as its size may grow in future releases of the API.
 126       Instead, it should be manually assembled by storing the
 127       <varname>size</varname>, <varname>type</varname> and payload to a
 128       struct of its own.
 129     </para>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>Item types</title>
 134
 135     <refsect2>
 136       <title>Negotiation item</title>
 137       <variablelist>
 138         <varlistentry>
 139           <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
 140           <listitem><para>
 141             With this item is attached to any ioctl, programs can
 142             <emphasis>probe</emphasis> the kernel for known item types.
 143             The item carries an array of <type>uint64_t</type> values in
 144             <varname>item.data64</varname>, each set to an item type to
 145             probe. The kernel will reset each member of this array that is
 146             not recognized as valid item type to <constant>0</constant>.
 147             This way, users can negotiate kernel features at start-up to
 148             keep newer userspace compatible with older kernels. This item
 149             is never attached by the kernel in response to any command.
 150           </para></listitem>
 151         </varlistentry>
 152       </variablelist>
 153     </refsect2>
 154
 155     <refsect2>
 156       <title>Command specific items</title>
 157       <variablelist>
 158         <varlistentry>
 159           <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
 160           <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
 161           <listitem><para>
 162             Messages are directly copied by the sending process into the
 163             receiver's
 164             <citerefentry>
 165               <refentrytitle>kdbus.pool</refentrytitle>
 166               <manvolnum>7</manvolnum>
 167             </citerefentry>.
 168             This way, two peers can exchange data by effectively doing a
 169             single-copy from one process to another; the kernel will not buffer
 170             the data anywhere else. <constant>KDBUS_ITEM_PAYLOAD_VEC</constant>
 171             is used when <emphasis>sending</emphasis> message. The item
 172             references a memory address when the payload data can be found.
 173             <constant>KDBUS_ITEM_PAYLOAD_OFF</constant> is used when messages
 174             are <emphasis>received</emphasis>, and the
 175             <constant>offset</constant> value describes the offset inside the
 176             receiving connection's
 177             <citerefentry>
 178               <refentrytitle>kdbus.pool</refentrytitle>
 179               <manvolnum>7</manvolnum>
 180             </citerefentry>
 181             where the message payload can be found. See
 182             <citerefentry>
 183               <refentrytitle>kdbus.message</refentrytitle>
 184               <manvolnum>7</manvolnum>
 185             </citerefentry>
 186             for more information on passing of payload data along with a
 187             message.
 188             <programlisting>
 189 struct kdbus_vec {
 190   __u64 size;
 191   union {
 192     __u64 address;
 193     __u64 offset;
 194   };
 195 };
 196             </programlisting>
 197           </para></listitem>
 198         </varlistentry>
 199
 200         <varlistentry>
 201           <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
 202           <listitem><para>
 203             Transports a file descriptor of a <emphasis>memfd</emphasis> in
 204             <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
 205             The <varname>size</varname> field has to match the actual size of
 206             the memfd that was specified when it was created. The
 207             <varname>start</varname> parameter denotes the offset inside the
 208             memfd at which the referenced payload starts. See
 209             <citerefentry>
 210               <refentrytitle>kdbus.message</refentrytitle>
 211               <manvolnum>7</manvolnum>
 212             </citerefentry>
 213             for more information on passing of payload data along with a
 214             message.
 215             <programlisting>
 216 struct kdbus_memfd {
 217   __u64 start;
 218   __u64 size;
 219   int fd;
 220   __u32 __pad;
 221 };
 222             </programlisting>
 223           </para></listitem>
 224         </varlistentry>
 225
 226         <varlistentry>
 227           <term><constant>KDBUS_ITEM_FDS</constant></term>
 228           <listitem><para>
 229             Contains an array of <emphasis>file descriptors</emphasis>.
 230             When used with <constant>KDBUS_CMD_SEND</constant>, the values of
 231             this array must be filled with valid file descriptor numbers.
 232             When received as item attached to a message, the array will
 233             contain the numbers of the installed file descriptors, or
 234             <constant>-1</constant> in case an error occurred.
 235             In either case, the number of entries in the array is derived from
 236             the item's total size. See
 237             <citerefentry>
 238               <refentrytitle>kdbus.message</refentrytitle>
 239               <manvolnum>7</manvolnum>
 240             </citerefentry>
 241             for more information.
 242           </para></listitem>
 243         </varlistentry>
 244       </variablelist>
 245     </refsect2>
 246
 247     <refsect2>
 248       <title>Items specific to some commands</title>
 249       <variablelist>
 250         <varlistentry>
 251           <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
 252           <listitem><para>
 253             Transports a file descriptor that can be used to cancel a
 254             synchronous <constant>KDBUS_CMD_SEND</constant> operation by
 255             writing to it. The file descriptor is stored in
 256             <varname>item.fd[0]</varname>. The item may only contain one
 257             file descriptor. See
 258             <citerefentry>
 259               <refentrytitle>kdbus.message</refentrytitle>
 260               <manvolnum>7</manvolnum>
 261             </citerefentry>
 262             for more information on this item and how to use it.
 263           </para></listitem>
 264         </varlistentry>
 265
 266         <varlistentry>
 267           <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
 268           <listitem><para>
 269             Contains a set of <emphasis>bloom parameters</emphasis> as
 270             <type>struct kdbus_bloom_parameter</type> in
 271             <varname>item.bloom_parameter</varname>.
 272             The item is passed from userspace to kernel during the
 273             <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl, and returned
 274             verbatim when <constant>KDBUS_CMD_HELLO</constant> is called.
 275             The kernel does not use the bloom parameters, but they need to
 276             be known by each connection on the bus in order to define the
 277             bloom filter hash details. See
 278             <citerefentry>
 279               <refentrytitle>kdbus.match</refentrytitle>
 280               <manvolnum>7</manvolnum>
 281             </citerefentry>
 282             for more information on matching and bloom filters.
 283             <programlisting>
 284 struct kdbus_bloom_parameter {
 285   __u64 size;
 286   __u64 n_hash;
 287 };
 288             </programlisting>
 289           </para></listitem>
 290         </varlistentry>
 291
 292         <varlistentry>
 293           <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
 294           <listitem><para>
 295             Carries a <emphasis>bloom filter</emphasis> as
 296             <type>struct kdbus_bloom_filter</type> in
 297             <varname>item.bloom_filter</varname>. It is mandatory to send this
 298             item attached to a <type>struct kdbus_msg</type>, in case the
 299             message is a signal. This item is never transported from kernel to
 300             userspace. See
 301             <citerefentry>
 302               <refentrytitle>kdbus.match</refentrytitle>
 303               <manvolnum>7</manvolnum>
 304             </citerefentry>
 305             for more information on matching and bloom filters.
 306             <programlisting>
 307 struct kdbus_bloom_filter {
 308   __u64 generation;
 309   __u64 data[0];
 310 };
 311             </programlisting>
 312           </para></listitem>
 313         </varlistentry>
 314
 315         <varlistentry>
 316           <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
 317           <listitem><para>
 318             Transports a <emphasis>bloom mask</emphasis> as binary data blob
 319             stored in <varname>item.data</varname>. This item is used to
 320             describe a match into a connection's match database. See
 321             <citerefentry>
 322               <refentrytitle>kdbus.match</refentrytitle>
 323               <manvolnum>7</manvolnum>
 324             </citerefentry>
 325             for more information on matching and bloom filters.
 326           </para></listitem>
 327         </varlistentry>
 328
 329         <varlistentry>
 330           <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
 331           <listitem><para>
 332             Contains a <emphasis>well-known name</emphasis> to send a
 333             message to, as null-terminated string in
 334             <varname>item.str</varname>. This item is used with
 335             <constant>KDBUS_CMD_SEND</constant>. See
 336             <citerefentry>
 337               <refentrytitle>kdbus.message</refentrytitle>
 338               <manvolnum>7</manvolnum>
 339             </citerefentry>
 340             for more information on how to send a message.
 341           </para></listitem>
 342         </varlistentry>
 343
 344         <varlistentry>
 345           <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
 346           <listitem><para>
 347             Contains a <emphasis>bus name</emphasis> or
 348             <emphasis>endpoint name</emphasis>, stored as null-terminated
 349             string in <varname>item.str</varname>. This item is sent from
 350             userspace to kernel when buses or endpoints are created, and
 351             returned back to userspace when the bus creator information is
 352             queried. See
 353             <citerefentry>
 354               <refentrytitle>kdbus.bus</refentrytitle>
 355               <manvolnum>7</manvolnum>
 356             </citerefentry>
 357             and
 358             <citerefentry>
 359               <refentrytitle>kdbus.endpoint</refentrytitle>
 360               <manvolnum>7</manvolnum>
 361             </citerefentry>.
 362           </para></listitem>
 363         </varlistentry>
 364
 365         <varlistentry>
 366           <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
 367           <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
 368           <listitem><para>
 369             Contains a set of <emphasis>attach flags</emphasis> at
 370             <emphasis>send</emphasis> or <emphasis>receive</emphasis> time. See
 371             <citerefentry>
 372               <refentrytitle>kdbus</refentrytitle>
 373               <manvolnum>7</manvolnum>
 374             </citerefentry>,
 375             <citerefentry>
 376               <refentrytitle>kdbus.bus</refentrytitle>
 377               <manvolnum>7</manvolnum>
 378             </citerefentry> and
 379             <citerefentry>
 380               <refentrytitle>kdbus.connection</refentrytitle>
 381               <manvolnum>7</manvolnum>
 382             </citerefentry>
 383             for more information on attach flags.
 384           </para></listitem>
 385         </varlistentry>
 386
 387         <varlistentry>
 388           <term><constant>KDBUS_ITEM_ID</constant></term>
 389           <listitem><para>
 390             Transports a connection's <emphasis>numerical ID</emphasis> of
 391             a connection as <type>uint64_t</type> value in
 392             <varname>item.id</varname>.
 393           </para></listitem>
 394         </varlistentry>
 395
 396         <varlistentry>
 397           <term><constant>KDBUS_ITEM_NAME</constant></term>
 398           <listitem><para>
 399             Transports a name associated with the
 400             <emphasis>name registry</emphasis> as null-terminated string as
 401             <type>struct kdbus_name</type> in
 402             <varname>item.name</varname>. The <varname>flags</varname>
 403             contains the flags of the name. See
 404             <citerefentry>
 405               <refentrytitle>kdbus.name</refentrytitle>
 406               <manvolnum>7</manvolnum>
 407             </citerefentry>
 408             for more information on how to access the name registry of a bus.
 409             <programlisting>
 410 struct kdbus_name {
 411   __u64 flags;
 412   char name[0];
 413 };
 414             </programlisting>
 415           </para></listitem>
 416         </varlistentry>
 417       </variablelist>
 418     </refsect2>
 419
 420     <refsect2>
 421       <title>Items attached by the kernel as metadata</title>
 422
 423       <variablelist>
 424         <varlistentry>
 425           <term><constant>KDBUS_ITEM_TIMESTAMP</constant></term>
 426           <listitem><para>
 427             Contains both the <emphasis>monotonic</emphasis> and the
 428             <emphasis>realtime</emphasis> timestamp, taken when the message
 429             was processed on the kernel side.
 430             Stored as <type>struct kdbus_timestamp</type> in
 431             <varname>item.timestamp</varname>.
 432             <programlisting>
 433 struct kdbus_timestamp {
 434   __u64 seqnum;
 435   __u64 monotonic_ns;
 436   __u64 realtime_ns;
 437 };
 438             </programlisting>
 439           </para></listitem>
 440         </varlistentry>
 441
 442         <varlistentry>
 443           <term><constant>KDBUS_ITEM_CREDS</constant></term>
 444           <listitem><para>
 445             Contains a set of <emphasis>user</emphasis> and
 446             <emphasis>group</emphasis> information as 32-bit values, in the
 447             usual four flavors: real, effective, saved and filesystem related.
 448             Stored as <type>struct kdbus_creds</type> in
 449             <varname>item.creds</varname>.
 450             <programlisting>
 451 struct kdbus_creds {
 452   __u32 uid;
 453   __u32 euid;
 454   __u32 suid;
 455   __u32 fsuid;
 456   __u32 gid;
 457   __u32 egid;
 458   __u32 sgid;
 459   __u32 fsgid;
 460 };
 461             </programlisting>
 462           </para></listitem>
 463         </varlistentry>
 464
 465         <varlistentry>
 466           <term><constant>KDBUS_ITEM_PIDS</constant></term>
 467           <listitem><para>
 468             Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
 469             and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
 470             Stored as <type>struct kdbus_pids</type> in
 471             <varname>item.pids</varname>.
 472             <programlisting>
 473 struct kdbus_pids {
 474   __u64 pid;
 475   __u64 tid;
 476   __u64 ppid;
 477 };
 478             </programlisting>
 479           </para></listitem>
 480         </varlistentry>
 481
 482         <varlistentry>
 483           <term><constant>KDBUS_ITEM_AUXGROUPS</constant></term>
 484           <listitem><para>
 485             Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
 486             a remote peer is a member of, stored as array of
 487             <type>uint32_t</type> values in <varname>item.data32</varname>.
 488             The array length can be determined by looking at the item's total
 489             size, subtracting the size of the header and dividing the
 490             remainder by <constant>sizeof(uint32_t)</constant>.
 491           </para></listitem>
 492         </varlistentry>
 493
 494         <varlistentry>
 495           <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
 496           <listitem><para>
 497             Contains a <emphasis>well-known name</emphasis> currently owned
 498             by a connection. The name is stored as null-terminated string in
 499             <varname>item.str</varname>. Its length can also be derived from
 500             the item's total size.
 501           </para></listitem>
 502         </varlistentry>
 503
 504         <varlistentry>
 505           <term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
 506           <listitem><para>
 507             Contains the <emphasis>comm</emphasis> string of a task's
 508             <emphasis>TID</emphasis> (thread ID), stored as null-terminated
 509             string in <varname>item.str</varname>. Its length can also be
 510             derived from the item's total size. Receivers of this item should
 511             not use its contents for any kind of security measures. See below.
 512           </para></listitem>
 513         </varlistentry>
 514
 515         <varlistentry>
 516           <term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
 517           <listitem><para>
 518             Contains the <emphasis>comm</emphasis> string of a task's
 519             <emphasis>PID</emphasis> (process ID), stored as null-terminated
 520             string in <varname>item.str</varname>. Its length can also be
 521             derived from the item's total size. Receivers of this item should
 522             not use its contents for any kind of security measures. See below.
 523           </para></listitem>
 524         </varlistentry>
 525
 526         <varlistentry>
 527           <term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
 528           <listitem><para>
 529             Contains the <emphasis>path to the executable</emphasis> of a task,
 530             stored as null-terminated string in <varname>item.str</varname>. Its
 531             length can also be derived from the item's total size. Receivers of
 532             this item should not use its contents for any kind of security
 533             measures. See below.
 534           </para></listitem>
 535         </varlistentry>
 536
 537         <varlistentry>
 538           <term><constant>KDBUS_ITEM_CMDLINE</constant> [*]</term>
 539           <listitem><para>
 540             Contains the <emphasis>command line arguments</emphasis> of a
 541             task, stored as an <emphasis>array</emphasis> of null-terminated
 542             strings in <varname>item.str</varname>. The total length of all
 543             strings in the array can be derived from the item's total size.
 544             Receivers of this item should not use its contents for any kind
 545             of security measures. See below.
 546           </para></listitem>
 547         </varlistentry>
 548
 549         <varlistentry>
 550           <term><constant>KDBUS_ITEM_CGROUP</constant></term>
 551           <listitem><para>
 552             Contains the <emphasis>cgroup path</emphasis> of a task, stored
 553             as null-terminated string in <varname>item.str</varname>. Its
 554             length can also be derived from the item's total size.
 555           </para></listitem>
 556         </varlistentry>
 557
 558         <varlistentry>
 559           <term><constant>KDBUS_ITEM_CAPS</constant></term>
 560           <listitem><para>
 561             Contains sets of <emphasis>capabilities</emphasis>, stored as
 562             <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
 563             As the item size may increase in the future, programs should be
 564             written in a way that it takes
 565             <varname>item.caps.last_cap</varname> into account, and derive
 566             the number of sets and rows from the item size and the reported
 567             number of valid capability bits.
 568             <programlisting>
 569 struct kdbus_caps {
 570   __u32 last_cap;
 571   __u32 caps[0];
 572 };
 573             </programlisting>
 574           </para></listitem>
 575         </varlistentry>
 576
 577         <varlistentry>
 578           <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
 579           <listitem><para>
 580             Contains the <emphasis>LSM label</emphasis> of a task, stored as
 581             null-terminated string in <varname>item.str</varname>. Its length
 582             can also be derived from the item's total size.
 583           </para></listitem>
 584         </varlistentry>
 585
 586         <varlistentry>
 587           <term><constant>KDBUS_ITEM_AUDIT</constant></term>
 588           <listitem><para>
 589             Contains the audit <emphasis>sessionid</emphasis> and
 590             <emphasis>loginuid</emphasis> of a task, stored as
 591             <type>struct kdbus_audit</type> in
 592             <varname>item.audit</varname>.
 593             <programlisting>
 594 struct kdbus_audit {
 595   __u32 sessionid;
 596   __u32 loginuid;
 597 };
 598             </programlisting>
 599           </para></listitem>
 600         </varlistentry>
 601
 602         <varlistentry>
 603           <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
 604           <listitem><para>
 605             Contains the <emphasis>connection description</emphasis>, as set
 606             by <constant>KDBUS_CMD_HELLO</constant> or
 607             <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
 608             null-terminated string in <varname>item.str</varname>. Its length
 609             can also be derived from the item's total size.
 610           </para></listitem>
 611         </varlistentry>
 612       </variablelist>
 613
 614       <para>
 615         All metadata is automatically translated into the
 616         <emphasis>namespaces</emphasis> of the task that receives them. See
 617         <citerefentry>
 618           <refentrytitle>kdbus.message</refentrytitle>
 619           <manvolnum>7</manvolnum>
 620         </citerefentry>
 621         for more information.
 622       </para>
 623
 624       <para>
 625         [*] Note that the content stored in metadata items of type
 626         <constant>KDBUS_ITEM_TID_COMM</constant>,
 627         <constant>KDBUS_ITEM_PID_COMM</constant>,
 628         <constant>KDBUS_ITEM_EXE</constant> and
 629         <constant>KDBUS_ITEM_CMDLINE</constant>
 630         can easily be tampered by the sending tasks. Therefore, they should
 631         <emphasis>not</emphasis> be used for any sort of security relevant
 632         assumptions. The only reason they are transmitted is to let
 633         receivers know about details that were set when metadata was
 634         collected, even though the task they were collected from is not
 635         active any longer when the items are received.
 636       </para>
 637     </refsect2>
 638
 639     <refsect2>
 640       <title>Items used for policy entries, matches and notifications</title>
 641
 642       <variablelist>
 643         <varlistentry>
 644           <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
 645           <listitem><para>
 646             This item describes a <emphasis>policy access</emphasis> entry to
 647             access the policy database of a
 648             <citerefentry>
 649               <refentrytitle>kdbus.bus</refentrytitle>
 650               <manvolnum>7</manvolnum>
 651             </citerefentry> or
 652             <citerefentry>
 653               <refentrytitle>kdbus.endpoint</refentrytitle>
 654               <manvolnum>7</manvolnum>
 655             </citerefentry>.
 656             Please refer to
 657             <citerefentry>
 658               <refentrytitle>kdbus.policy</refentrytitle>
 659               <manvolnum>7</manvolnum>
 660             </citerefentry>
 661             for more information on the policy database and how to access it.
 662             <programlisting>
 663 struct kdbus_policy_access {
 664   __u64 type;
 665   __u64 access;
 666   __u64 id;
 667 };
 668             </programlisting>
 669           </para></listitem>
 670         </varlistentry>
 671
 672         <varlistentry>
 673           <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
 674           <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
 675           <listitem><para>
 676             This item is sent as attachment to a
 677             <emphasis>kernel notification</emphasis> and indicates that a
 678             new connection was created on the bus, or that a connection was
 679             disconnected, respectively. It stores a
 680             <type>struct kdbus_notify_id_change</type> in
 681             <varname>item.id_change</varname>.
 682             The <varname>id</varname> field contains the numeric ID of the
 683             connection that was added or removed, and <varname>flags</varname>
 684             is set to the connection flags, as passed by
 685             <constant>KDBUS_CMD_HELLO</constant>. See
 686             <citerefentry>
 687               <refentrytitle>kdbus.match</refentrytitle>
 688               <manvolnum>7</manvolnum>
 689             </citerefentry>
 690             and
 691             <citerefentry>
 692               <refentrytitle>kdbus.message</refentrytitle>
 693               <manvolnum>7</manvolnum>
 694             </citerefentry>
 695             for more information on matches and notification messages.
 696             <programlisting>
 697 struct kdbus_notify_id_change {
 698   __u64 id;
 699   __u64 flags;
 700 };
 701             </programlisting>
 702           </para></listitem>
 703         </varlistentry>
 704
 705         <varlistentry>
 706           <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
 707           <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
 708           <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
 709           <listitem><para>
 710             This item is sent as attachment to a
 711             <emphasis>kernel notification</emphasis> and indicates that a
 712             <emphasis>well-known name</emphasis> appeared, disappeared or
 713             transferred to another owner on the bus. It stores a
 714             <type>struct kdbus_notify_name_change</type> in
 715             <varname>item.name_change</varname>.
 716             <varname>old_id</varname> describes the former owner of the name
 717             and is set to <constant>0</constant> values in case of
 718             <constant>KDBUS_ITEM_NAME_ADD</constant>.
 719             <varname>new_id</varname> describes the new owner of the name and
 720             is set to <constant>0</constant> values in case of
 721             <constant>KDBUS_ITEM_NAME_REMOVE</constant>.
 722             The <varname>name</varname> field contains the well-known name the
 723             notification is about, as null-terminated string. See
 724             <citerefentry>
 725               <refentrytitle>kdbus.match</refentrytitle>
 726               <manvolnum>7</manvolnum>
 727             </citerefentry>
 728             and
 729             <citerefentry>
 730               <refentrytitle>kdbus.message</refentrytitle>
 731               <manvolnum>7</manvolnum>
 732             </citerefentry>
 733             for more information on matches and notification messages.
 734             <programlisting>
 735 struct kdbus_notify_name_change {
 736   struct kdbus_notify_id_change old_id;
 737   struct kdbus_notify_id_change new_id;
 738   char name[0];
 739 };
 740             </programlisting>
 741           </para></listitem>
 742         </varlistentry>
 743
 744         <varlistentry>
 745           <term><constant>KDBUS_ITEM_REPLY_TIMEOUT</constant></term>
 746           <listitem><para>
 747             This item is sent as attachment to a
 748             <emphasis>kernel notification</emphasis>. It informs the receiver
 749             that an expected reply to a message was not received in time.
 750             The remote peer ID and the message cookie are stored in the message
 751             header. See
 752             <citerefentry>
 753               <refentrytitle>kdbus.message</refentrytitle>
 754               <manvolnum>7</manvolnum>
 755             </citerefentry>
 756             for more information about messages, timeouts and notifications.
 757           </para></listitem>
 758         </varlistentry>
 759
 760         <varlistentry>
 761           <term><constant>KDBUS_ITEM_REPLY_DEAD</constant></term>
 762           <listitem><para>
 763             This item is sent as attachment to a
 764             <emphasis>kernel notification</emphasis>. It informs the receiver
 765             that a remote connection a reply is expected from was disconnected
 766             before that reply was sent. The remote peer ID and the message
 767             cookie are stored in the message header. See
 768             <citerefentry>
 769               <refentrytitle>kdbus.message</refentrytitle>
 770               <manvolnum>7</manvolnum>
 771             </citerefentry>
 772             for more information about messages, timeouts and notifications.
 773           </para></listitem>
 774         </varlistentry>
 775       </variablelist>
 776     </refsect2>
 777   </refsect1>
 778
 779   <refsect1>
 780     <title>See Also</title>
 781     <simplelist type="inline">
 782       <member>
 783         <citerefentry>
 784           <refentrytitle>kdbus</refentrytitle>
 785           <manvolnum>7</manvolnum>
 786         </citerefentry>
 787       </member>
 788       <member>
 789         <citerefentry>
 790           <refentrytitle>kdbus.bus</refentrytitle>
 791           <manvolnum>7</manvolnum>
 792         </citerefentry>
 793       </member>
 794       <member>
 795         <citerefentry>
 796           <refentrytitle>kdbus.connection</refentrytitle>
 797           <manvolnum>7</manvolnum>
 798         </citerefentry>
 799       </member>
 800       <member>
 801         <citerefentry>
 802           <refentrytitle>kdbus.endpoint</refentrytitle>
 803           <manvolnum>7</manvolnum>
 804         </citerefentry>
 805       </member>
 806       <member>
 807         <citerefentry>
 808           <refentrytitle>kdbus.fs</refentrytitle>
 809           <manvolnum>7</manvolnum>
 810         </citerefentry>
 811       </member>
 812       <member>
 813         <citerefentry>
 814           <refentrytitle>kdbus.message</refentrytitle>
 815           <manvolnum>7</manvolnum>
 816         </citerefentry>
 817       </member>
 818       <member>
 819         <citerefentry>
 820           <refentrytitle>kdbus.name</refentrytitle>
 821           <manvolnum>7</manvolnum>
 822         </citerefentry>
 823       </member>
 824       <member>
 825         <citerefentry>
 826           <refentrytitle>kdbus.pool</refentrytitle>
 827           <manvolnum>7</manvolnum>
 828         </citerefentry>
 829       </member>
 830       <member>
 831         <citerefentry>
 832           <refentrytitle>memfd_create</refentrytitle>
 833           <manvolnum>2</manvolnum>
 834         </citerefentry>
 835       </member>
 836     </simplelist>
 837   </refsect1>
 838
 839 </refentry>