summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.item.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kdbus/kdbus.item.xml')
-rw-r--r--Documentation/kdbus/kdbus.item.xml839
1 files changed, 839 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.item.xml b/Documentation/kdbus/kdbus.item.xml
new file mode 100644
index 000000000..ee09dfa44
--- /dev/null
+++ b/Documentation/kdbus/kdbus.item.xml
@@ -0,0 +1,839 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="kdbus">
+
+ <refentryinfo>
+ <title>kdbus.item</title>
+ <productname>kdbus item</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>kdbus.item</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kdbus.item</refname>
+ <refpurpose>kdbus item structure, layout and usage</refpurpose>
+ </refnamediv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>
+ To flexibly augment transport structures, data blobs of type
+ <type>struct kdbus_item</type> can be attached to the structs passed
+ into the ioctls. Some ioctls make items of certain types mandatory,
+ others are optional. Items that are unsupported by ioctls they are
+ attached to will cause the ioctl to fail with <varname>errno</varname>
+ set to <constant>EINVAL</constant>.
+ Items are also used for information stored in a connection's
+ <emphasis>pool</emphasis>, such as received messages, name lists or
+ requested connection or bus owner information. Depending on the type of
+ an item, its total size is either fixed or variable.
+ </para>
+
+ <refsect2>
+ <title>Chaining items</title>
+ <para>
+ Whenever items are used as part of the kdbus kernel API, they are
+ embedded in structs that are embedded inside structs that themselves
+ include a size field containing the overall size of the structure.
+ This allows multiple items to be chained up, and an item iterator
+ (see below) is capable of detecting the end of an item chain.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Alignment</title>
+ <para>
+ The kernel expects all items to be aligned to 8-byte boundaries.
+ Unaligned items will cause the ioctl they are used with to fail
+ with <varname>errno</varname> set to <constant>EINVAL</constant>.
+ An item that has an unaligned size itself hence needs to be padded
+ if it is followed by another item.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Iterating items</title>
+ <para>
+ A simple iterator would iterate over the items until the items have
+ reached the embedding structure's overall size. An example
+ implementation is shown below.
+ </para>
+
+ <programlisting><![CDATA[
+#define KDBUS_ALIGN8(val) (((val) + 7) & ~7)
+
+#define KDBUS_ITEM_NEXT(item) \
+ (typeof(item))((uint8_t *)(item) + KDBUS_ALIGN8((item)->size))
+
+#define KDBUS_ITEM_FOREACH(item, head, first) \
+ for ((item) = (head)->first; \
+ ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \
+ ((uint8_t *)(item) >= (uint8_t *)(head)); \
+ (item) = KDBUS_ITEM_NEXT(item))
+ ]]></programlisting>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Item layout</title>
+ <para>
+ A <type>struct kdbus_item</type> consists of a
+ <varname>size</varname> field, describing its overall size, and a
+ <varname>type</varname> field, both 64 bit wide. They are followed by
+ a union to store information that is specific to the item's type.
+ The struct layout is shown below.
+ </para>
+
+ <programlisting>
+struct kdbus_item {
+ __u64 size;
+ __u64 type;
+ /* item payload - see below */
+ union {
+ __u8 data[0];
+ __u32 data32[0];
+ __u64 data64[0];
+ char str[0];
+
+ __u64 id;
+ struct kdbus_vec vec;
+ struct kdbus_creds creds;
+ struct kdbus_pids pids;
+ struct kdbus_audit audit;
+ struct kdbus_caps caps;
+ struct kdbus_timestamp timestamp;
+ struct kdbus_name name;
+ struct kdbus_bloom_parameter bloom_parameter;
+ struct kdbus_bloom_filter bloom_filter;
+ struct kdbus_memfd memfd;
+ int fds[0];
+ struct kdbus_notify_name_change name_change;
+ struct kdbus_notify_id_change id_change;
+ struct kdbus_policy_access policy_access;
+ };
+};
+ </programlisting>
+
+ <para>
+ <type>struct kdbus_item</type> should never be used to allocate
+ an item instance, as its size may grow in future releases of the API.
+ Instead, it should be manually assembled by storing the
+ <varname>size</varname>, <varname>type</varname> and payload to a
+ struct of its own.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Item types</title>
+
+ <refsect2>
+ <title>Negotiation item</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NEGOTIATE</constant></term>
+ <listitem><para>
+ With this item is attached to any ioctl, programs can
+ <emphasis>probe</emphasis> the kernel for known item types.
+ The item carries an array of <type>uint64_t</type> values in
+ <varname>item.data64</varname>, each set to an item type to
+ probe. The kernel will reset each member of this array that is
+ not recognized as valid item type to <constant>0</constant>.
+ This way, users can negotiate kernel features at start-up to
+ keep newer userspace compatible with older kernels. This item
+ is never attached by the kernel in response to any command.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Command specific items</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_VEC</constant></term>
+ <term><constant>KDBUS_ITEM_PAYLOAD_OFF</constant></term>
+ <listitem><para>
+ Messages are directly copied by the sending process into the
+ receiver's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ This way, two peers can exchange data by effectively doing a
+ single-copy from one process to another; the kernel will not buffer
+ the data anywhere else. <constant>KDBUS_ITEM_PAYLOAD_VEC</constant>
+ is used when <emphasis>sending</emphasis> message. The item
+ references a memory address when the payload data can be found.
+ <constant>KDBUS_ITEM_PAYLOAD_OFF</constant> is used when messages
+ are <emphasis>received</emphasis>, and the
+ <constant>offset</constant> value describes the offset inside the
+ receiving connection's
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ where the message payload can be found. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_vec {
+ __u64 size;
+ union {
+ __u64 address;
+ __u64 offset;
+ };
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PAYLOAD_MEMFD</constant></term>
+ <listitem><para>
+ Transports a file descriptor of a <emphasis>memfd</emphasis> in
+ <type>struct kdbus_memfd</type> in <varname>item.memfd</varname>.
+ The <varname>size</varname> field has to match the actual size of
+ the memfd that was specified when it was created. The
+ <varname>start</varname> parameter denotes the offset inside the
+ memfd at which the referenced payload starts. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on passing of payload data along with a
+ message.
+ <programlisting>
+struct kdbus_memfd {
+ __u64 start;
+ __u64 size;
+ int fd;
+ __u32 __pad;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_FDS</constant></term>
+ <listitem><para>
+ Contains an array of <emphasis>file descriptors</emphasis>.
+ When used with <constant>KDBUS_CMD_SEND</constant>, the values of
+ this array must be filled with valid file descriptor numbers.
+ When received as item attached to a message, the array will
+ contain the numbers of the installed file descriptors, or
+ <constant>-1</constant> in case an error occurred.
+ In either case, the number of entries in the array is derived from
+ the item's total size. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items specific to some commands</title>
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CANCEL_FD</constant></term>
+ <listitem><para>
+ Transports a file descriptor that can be used to cancel a
+ synchronous <constant>KDBUS_CMD_SEND</constant> operation by
+ writing to it. The file descriptor is stored in
+ <varname>item.fd[0]</varname>. The item may only contain one
+ file descriptor. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on this item and how to use it.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_PARAMETER</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>bloom parameters</emphasis> as
+ <type>struct kdbus_bloom_parameter</type> in
+ <varname>item.bloom_parameter</varname>.
+ The item is passed from userspace to kernel during the
+ <constant>KDBUS_CMD_BUS_MAKE</constant> ioctl, and returned
+ verbatim when <constant>KDBUS_CMD_HELLO</constant> is called.
+ The kernel does not use the bloom parameters, but they need to
+ be known by each connection on the bus in order to define the
+ bloom filter hash details. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_parameter {
+ __u64 size;
+ __u64 n_hash;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_FILTER</constant></term>
+ <listitem><para>
+ Carries a <emphasis>bloom filter</emphasis> as
+ <type>struct kdbus_bloom_filter</type> in
+ <varname>item.bloom_filter</varname>. It is mandatory to send this
+ item attached to a <type>struct kdbus_msg</type>, in case the
+ message is a signal. This item is never transported from kernel to
+ userspace. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ <programlisting>
+struct kdbus_bloom_filter {
+ __u64 generation;
+ __u64 data[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_BLOOM_MASK</constant></term>
+ <listitem><para>
+ Transports a <emphasis>bloom mask</emphasis> as binary data blob
+ stored in <varname>item.data</varname>. This item is used to
+ describe a match into a connection's match database. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matching and bloom filters.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_DST_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> to send a
+ message to, as null-terminated string in
+ <varname>item.str</varname>. This item is used with
+ <constant>KDBUS_CMD_SEND</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to send a message.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_MAKE_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>bus name</emphasis> or
+ <emphasis>endpoint name</emphasis>, stored as null-terminated
+ string in <varname>item.str</varname>. This item is sent from
+ userspace to kernel when buses or endpoints are created, and
+ returned back to userspace when the bus creator information is
+ queried. See
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_SEND</constant></term>
+ <term><constant>KDBUS_ITEM_ATTACH_FLAGS_RECV</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>attach flags</emphasis> at
+ <emphasis>send</emphasis> or <emphasis>receive</emphasis> time. See
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on attach flags.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID</constant></term>
+ <listitem><para>
+ Transports a connection's <emphasis>numerical ID</emphasis> of
+ a connection as <type>uint64_t</type> value in
+ <varname>item.id</varname>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME</constant></term>
+ <listitem><para>
+ Transports a name associated with the
+ <emphasis>name registry</emphasis> as null-terminated string as
+ <type>struct kdbus_name</type> in
+ <varname>item.name</varname>. The <varname>flags</varname>
+ contains the flags of the name. See
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on how to access the name registry of a bus.
+ <programlisting>
+struct kdbus_name {
+ __u64 flags;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Items attached by the kernel as metadata</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TIMESTAMP</constant></term>
+ <listitem><para>
+ Contains both the <emphasis>monotonic</emphasis> and the
+ <emphasis>realtime</emphasis> timestamp, taken when the message
+ was processed on the kernel side.
+ Stored as <type>struct kdbus_timestamp</type> in
+ <varname>item.timestamp</varname>.
+ <programlisting>
+struct kdbus_timestamp {
+ __u64 seqnum;
+ __u64 monotonic_ns;
+ __u64 realtime_ns;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CREDS</constant></term>
+ <listitem><para>
+ Contains a set of <emphasis>user</emphasis> and
+ <emphasis>group</emphasis> information as 32-bit values, in the
+ usual four flavors: real, effective, saved and filesystem related.
+ Stored as <type>struct kdbus_creds</type> in
+ <varname>item.creds</varname>.
+ <programlisting>
+struct kdbus_creds {
+ __u32 uid;
+ __u32 euid;
+ __u32 suid;
+ __u32 fsuid;
+ __u32 gid;
+ __u32 egid;
+ __u32 sgid;
+ __u32 fsgid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PIDS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>PID</emphasis>, <emphasis>TID</emphasis>
+ and <emphasis>parent PID (PPID)</emphasis> of a remote peer.
+ Stored as <type>struct kdbus_pids</type> in
+ <varname>item.pids</varname>.
+ <programlisting>
+struct kdbus_pids {
+ __u64 pid;
+ __u64 tid;
+ __u64 ppid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUXGROUPS</constant></term>
+ <listitem><para>
+ Contains the <emphasis>auxiliary (supplementary) groups</emphasis>
+ a remote peer is a member of, stored as array of
+ <type>uint32_t</type> values in <varname>item.data32</varname>.
+ The array length can be determined by looking at the item's total
+ size, subtracting the size of the header and dividing the
+ remainder by <constant>sizeof(uint32_t)</constant>.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_OWNED_NAME</constant></term>
+ <listitem><para>
+ Contains a <emphasis>well-known name</emphasis> currently owned
+ by a connection. The name is stored as null-terminated string in
+ <varname>item.str</varname>. Its length can also be derived from
+ the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>TID</emphasis> (thread ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>PID</emphasis> (process ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>path to the executable</emphasis> of a task,
+ stored as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size. Receivers of
+ this item should not use its contents for any kind of security
+ measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CMDLINE</constant> [*]</term>
+ <listitem><para>
+ Contains the <emphasis>command line arguments</emphasis> of a
+ task, stored as an <emphasis>array</emphasis> of null-terminated
+ strings in <varname>item.str</varname>. The total length of all
+ strings in the array can be derived from the item's total size.
+ Receivers of this item should not use its contents for any kind
+ of security measures. See below.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CGROUP</constant></term>
+ <listitem><para>
+ Contains the <emphasis>cgroup path</emphasis> of a task, stored
+ as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CAPS</constant></term>
+ <listitem><para>
+ Contains sets of <emphasis>capabilities</emphasis>, stored as
+ <type>struct kdbus_caps</type> in <varname>item.caps</varname>.
+ As the item size may increase in the future, programs should be
+ written in a way that it takes
+ <varname>item.caps.last_cap</varname> into account, and derive
+ the number of sets and rows from the item size and the reported
+ number of valid capability bits.
+ <programlisting>
+struct kdbus_caps {
+ __u32 last_cap;
+ __u32 caps[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_SECLABEL</constant></term>
+ <listitem><para>
+ Contains the <emphasis>LSM label</emphasis> of a task, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_AUDIT</constant></term>
+ <listitem><para>
+ Contains the audit <emphasis>sessionid</emphasis> and
+ <emphasis>loginuid</emphasis> of a task, stored as
+ <type>struct kdbus_audit</type> in
+ <varname>item.audit</varname>.
+ <programlisting>
+struct kdbus_audit {
+ __u32 sessionid;
+ __u32 loginuid;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_CONN_DESCRIPTION</constant></term>
+ <listitem><para>
+ Contains the <emphasis>connection description</emphasis>, as set
+ by <constant>KDBUS_CMD_HELLO</constant> or
+ <constant>KDBUS_CMD_CONN_UPDATE</constant>, stored as
+ null-terminated string in <varname>item.str</varname>. Its length
+ can also be derived from the item's total size.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ All metadata is automatically translated into the
+ <emphasis>namespaces</emphasis> of the task that receives them. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information.
+ </para>
+
+ <para>
+ [*] Note that the content stored in metadata items of type
+ <constant>KDBUS_ITEM_TID_COMM</constant>,
+ <constant>KDBUS_ITEM_PID_COMM</constant>,
+ <constant>KDBUS_ITEM_EXE</constant> and
+ <constant>KDBUS_ITEM_CMDLINE</constant>
+ can easily be tampered by the sending tasks. Therefore, they should
+ <emphasis>not</emphasis> be used for any sort of security relevant
+ assumptions. The only reason they are transmitted is to let
+ receivers know about details that were set when metadata was
+ collected, even though the task they were collected from is not
+ active any longer when the items are received.
+ </para>
+ </refsect2>
+
+ <refsect2>
+ <title>Items used for policy entries, matches and notifications</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_POLICY_ACCESS</constant></term>
+ <listitem><para>
+ This item describes a <emphasis>policy access</emphasis> entry to
+ access the policy database of a
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry> or
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+ Please refer to
+ <citerefentry>
+ <refentrytitle>kdbus.policy</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on the policy database and how to access it.
+ <programlisting>
+struct kdbus_policy_access {
+ __u64 type;
+ __u64 access;
+ __u64 id;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_ID_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_ID_REMOVE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ new connection was created on the bus, or that a connection was
+ disconnected, respectively. It stores a
+ <type>struct kdbus_notify_id_change</type> in
+ <varname>item.id_change</varname>.
+ The <varname>id</varname> field contains the numeric ID of the
+ connection that was added or removed, and <varname>flags</varname>
+ is set to the connection flags, as passed by
+ <constant>KDBUS_CMD_HELLO</constant>. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_id_change {
+ __u64 id;
+ __u64 flags;
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_NAME_ADD</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_REMOVE</constant></term>
+ <term><constant>KDBUS_ITEM_NAME_CHANGE</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis> and indicates that a
+ <emphasis>well-known name</emphasis> appeared, disappeared or
+ transferred to another owner on the bus. It stores a
+ <type>struct kdbus_notify_name_change</type> in
+ <varname>item.name_change</varname>.
+ <varname>old_id</varname> describes the former owner of the name
+ and is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_ADD</constant>.
+ <varname>new_id</varname> describes the new owner of the name and
+ is set to <constant>0</constant> values in case of
+ <constant>KDBUS_ITEM_NAME_REMOVE</constant>.
+ The <varname>name</varname> field contains the well-known name the
+ notification is about, as null-terminated string. See
+ <citerefentry>
+ <refentrytitle>kdbus.match</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information on matches and notification messages.
+ <programlisting>
+struct kdbus_notify_name_change {
+ struct kdbus_notify_id_change old_id;
+ struct kdbus_notify_id_change new_id;
+ char name[0];
+};
+ </programlisting>
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_TIMEOUT</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that an expected reply to a message was not received in time.
+ The remote peer ID and the message cookie are stored in the message
+ header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>KDBUS_ITEM_REPLY_DEAD</constant></term>
+ <listitem><para>
+ This item is sent as attachment to a
+ <emphasis>kernel notification</emphasis>. It informs the receiver
+ that a remote connection a reply is expected from was disconnected
+ before that reply was sent. The remote peer ID and the message
+ cookie are stored in the message header. See
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ for more information about messages, timeouts and notifications.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <simplelist type="inline">
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.bus</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.connection</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.endpoint</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.fs</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.message</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.name</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>kdbus.pool</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>
+ </member>
+ <member>
+ <citerefentry>
+ <refentrytitle>memfd_create</refentrytitle>
+ <manvolnum>2</manvolnum>
+ </citerefentry>
+ </member>
+ </simplelist>
+ </refsect1>
+
+</refentry>