kdbus.txt: Incorporate changes proposed by Michael Kerrisk

Signed-off-by: Daniel Mack <daniel@zonque.org>

1 files changed, 278 insertions, 225 deletions

diff --git a/kdbus.txt b/kdbus.txt
index b2392ea574e..6a00805966a 100644
--- a/kdbus.txt
+++ b/kdbus.txt
@@ -25,21 +25,23 @@ Articles about D-Bus and kdbus:
 ===============================================================================
 
   Domain:
-    A domain is created each time a kdbusfs is mounted. Each process that is
-    capable to mount a new instance of a kdbusfs will have its own kdbus
-    hierarchy. Each domain (ie, each mount point) offers its own "control"
-    file to create new buses. Domains have no connection to each other and
-    cannot see nor talk to each other. See section 5 for more details.
+    A domain is created each time a kdbusfs is mounted. Each process that
+    mounts a new instance of a kdbusfs will have its own kdbus hierarchy. Each
+    domain (ie, each mount point) offers its own "control" file to create new
+    buses. Domains have no connection to each other and can neither see nor
+    talk to each other. See section 5 for more details.
 
   Bus:
     A bus is a named object inside a domain. Clients exchange messages
     over a bus. Multiple buses themselves have no connection to each other;
     messages can only be exchanged on the same bus. The default endpoint of
-    a bus, where clients establish the connection to, is the "bus" file
+    a bus, to which clients establish connections to, is the "bus" file
     /sys/fs/kdbus/<bus name>/bus.
     Common operating system setups create one "system bus" per system, and one
     "user bus" for every logged-in user. Applications or services may create
-    their own private buses.  See section 5 for more details.
+    their own private buses. The kernel driver does not distinguish between
+    different bus types, they are all handled the same way.
+    See section 5 for more details.
 
   Endpoint:
     An endpoint provides a file to talk to a bus. Opening an endpoint
@@ -56,56 +58,60 @@ Articles about D-Bus and kdbus:
     A connection to a bus is created by opening an endpoint file of a bus and
     becoming an active client with the HELLO exchange. Every ordinary client
     connection has a unique identifier on the bus and can address messages to
-    every other connection on the same bus by using the peer's connection id
+    every other connection on the same bus by using the peer's connection ID
     as the destination.  See section 6 for more details.
 
   Pool:
     Each connection allocates a piece of shmem-backed memory that is used
     to receive messages and answers to ioctl commands from the kernel. It is
     never used to send anything to the kernel. In order to access that memory,
-    userspace must mmap() it into its address space.
+    a userspace application must mmap() it into its address space.
     See section 12 for more details.
 
   Well-known Name:
-    A connection can, in addition to its implicit unique connection id, request
+    A connection can, in addition to its implicit unique connection ID, request
     the ownership of a textual well-known name. Well-known names are noted in
-    reverse-domain notation, such as com.example.service1. Connections offering
-    a service on a bus are usually reached by its well-known name. The analogy
-    of connection id and well-known name is an IP address and a DNS name
-    associated with that address.
+    reverse-domain notation, such as com.example.service1. A connection that
+    offers a service on a bus is usually reached by its well-known name. The
+    analogy of connection ID and well-known name is an IP address and a DNS
+    name associated with that address.
 
   Message:
     Connections can exchange messages with other connections by addressing
-    the peers with their connection id or well-known name. A message consists
-    of a message header with kernel-specific information on how to route the
-    message, and the message payload, which is a logical byte stream of
-    arbitrary size. Messages can carry additional file descriptors to be passed
-    from one connection to another. Every connection can specify which set of
-    metadata the kernel should attach to the message when it is delivered
-    to the receiving connection. Metadata contains information like: system
-    timestamps, uid, gid, tid, proc-starttime, well-known-names, process comm,
-    process exe, process argv, cgroup, capabilities, seclabel, audit session,
-    loginuid and the connection's human-readable name.
-    See section 7 and 13 for more details.
+    the peers with their connection ID or well-known name. A message consists
+    of a message header with information on how to route the message, and the
+    message payload, which is a logical byte stream of arbitrary size.
+    Messages can carry additional file descriptors to be passed from one
+    connection to another, just like passing file descriptors over UNIX domain
+    sockets. Every connection can specify which set of metadata the kernel
+    should attach to the message when it is delivered to the receiving
+    connection. Metadata contains information like: system timestamps, UID, GID,
+    TID, proc-starttime, well-known names, process comm, process exe, process
+    argv, cgroup, capabilities, seclabel, audit session, loginuid and the
+    connection's human-readable name. See section 7 and 13 for more details.
 
   Item:
-    The API of kdbus implements a notion of items, submitted through and
+    The API of kdbus implements the notion of items, submitted through and
     returned by most ioctls, and stored inside data structures in the
     connection's pool. See section 4 for more details.
 
-  Broadcast and Match:
-    Broadcast messages are potentially sent to all connections of a bus. By
-    default, the connections will not actually receive any of the sent
-    broadcast messages; only after installing a match for specific message
-    properties, a broadcast message passes this filter.
+  Broadcast, signal, filter and match:
+    Signals are messages that a receiver opts in for by installing a blob of
+    bytes, called a 'match'. Signal messages must always carry a counter-part
+    blob, called a 'filter', and signals are only delivered to peers which have
+    a match that whitelists the message's filter.
+
+    Senders of signal messages can use either a single connection ID as
+    receiver, or KDBUS_DST_ID_BROADCAST to potentially send it to all
+    connections of a bus, following the logic described above.
+
     See section 10 for more details.
 
   Policy:
     A policy is a set of rules that define which connections can see, talk to,
-    or register a well-know name on the bus. A policy is attached to buses and
+    or register a well-known name on the bus. A policy is attached to buses and
     custom endpoints, and modified by policy holder connections or owners of
     custom endpoints. See section 11 for more details.
-    See section 11 for more details.
 
   Privileged bus users:
     A user connecting to the bus is considered privileged if it is either the
@@ -120,12 +126,12 @@ The kdbus interface is exposed through files in its kdbusfs mount point
 
   /sys/fs/kdbus                 (mount point of kdbusfs)
   |-- control                   (domain control-file)
-  |-- 0-system                  (bus of user uid=0)
+  |-- 0-system                  (bus of user UID=0)
   |   |-- bus                   (default endpoint of bus '0-system')
   |   `-- ep.apache             (custom endpoint of bus '0-system')
-  |-- 1000-user                 (bus of user uid=1000)
+  |-- 1000-user                 (bus of user UID=1000)
   |   `-- bus                   (default endpoint of bus '1000-user')
-  `-- 2702-user                 (bus of user uid=2702)
+  `-- 2702-user                 (bus of user UID=2702)
       |-- bus                   (default endpoint of bus '2702-user')
       `-- ep.app                (custom endpoint of bus '2702-user')
 
@@ -169,7 +175,7 @@ The kdbus interface is exposed through files in its kdbusfs mount point
 The above description uses the D-Bus notation of unique connection names that
 adds a ":1." prefix to the connection's unique ID. kdbus itself doesn't
 use that notation, neither internally nor externally. However, libraries and
-other userspace code that aims for compatibility to D-Bus might.
+other userspace code that aims for compatibility  D-Bus might.
 
 3.2 Flags
 ---------
@@ -207,11 +213,12 @@ Items are also used for information stored in a connection's pool, such as
 received messages, name lists or requested connection or bus owner information.
 
 Whenever items are used as part of the kdbus kernel API, they are embedded in
-structs that have an overall size of their own, so there can be multiple items
-per ioctl.
+structs that are embedded insides structs that themselves include a size field
+containing the overall size of the structure. This allows multiple items per
+ioctl.
 
 The kernel expects all items to be aligned to 8-byte boundaries. Unaligned
-items or such that are unsupported by the ioctl are rejected.
+items or items that are unsupported by the ioctl are rejected.
 
 A simple iterator in userspace would iterate over the items until the items
 have reached the embedding structure's overall size. An example implementation
@@ -229,9 +236,8 @@ A domain is a container of buses. Domains themselves do not provide any IPC
 functionality. Their sole purpose is to manage buses allocated in their
 domain. Each time kdbusfs is mounted, a new kdbus domain is created, with its
 own 'control' file. The lifetime of the domain ends once the user has unmounted
-the kdbusfs. If you mount kdbusfs multiple times, each will have its own kdbus
-domain internally. Operations performed on one domain do not affect any
-other domain.
+the kdbusfs. Each kdbusfs mount instance has its own kdbus domain. Operations
+performed on one domain do not affect any other domain.
 
 The full kdbusfs hierarchy, any sub-directory, or file can be bind-mounted to
 an external mount point and will remain fully functional. The kdbus domain and
@@ -239,56 +245,56 @@ any linked resources stay available until the original mount and all subsequent
 bind-mounts have been unmounted.
 
 During creation, domains pin the user-namespace of the creator and use
-it as controlling user-namespace for this domain. Any user accounting is done
-relative to that user-namespace.
+it for bus and endpoint name UID verification.
 
 Newly created kdbus domains do not have any bus pre-created. The only resource
 available is a 'control' file, which is used to manage kdbus domains.
-Currently, 'control' files are exclusively used to create buses via
+Currently, 'control' files are used exclusively to create buses via
 KDBUS_CMD_BUS_MAKE, but further ioctls might be added in the future.
 
 
 5.2 Buses
 ---------
 
-A bus is a shared resource between connections to transmit messages. Each bus
-is independent and operations on the bus will not have any effect on other
-buses. A bus is a management entity, that controls the addresses of its
-connections, their policies and message transactions performed via this bus.
+A bus is a shared resource between connections to transmit messages
+
+A bus is a resource that is shared between connections in order to transmit
+messages. Each bus is independent and operations on the bus will not have any
+effect on other buses. A bus is a management entity, that controls the
+addresses of its connections, their policies and message transactions performed
+via this bus.
 
 Each bus is bound to the domain it was created on. It has a custom name that is
 unique across all buses of a domain. In kdbusfs, a bus is presented as a
-directory. No operations can be performed on the bus itself, instead you need
-to perform those on an endpoint associated with the bus. Endpoints are
+directory. No operations can be performed on the bus itself; instead you need
+to perform the operations on an endpoint associated with the bus. Endpoints are
 accessible as files underneath the bus directory. A default endpoint called
 "bus" is provided on each bus.
 
 Bus names may be chosen freely except for one restriction: the name
-must be prefixed with the numeric UID of the creator and a dash. This
-is required to avoid namespace clashes between different users. When
-creating a bus the name must be passed in properly formatted, or the
-kernel will refuse creation of the bus. Example: "1047-foobar" is an
-OK name for a bus registered by a user with UID 1047. However,
-"1024-foobar" is not, and neither is "foobar".
-The UID must be provided in the user-namespace of the parent domain.
-
-To create a new bus, you need to open the control file of a domain and run the
-KDBUS_CMD_BUS_MAKE ioctl. The control file descriptor that was used to issue
-KDBUS_CMD_BUS_MAKE must not have been used for any other control-ioctl before
-and needs to be kept open for the entire life-time of the created bus. Closing
-it will immediately cleanup the entire bus and all its associated resources and
-endpoints. Every control file descriptor can only be used to create a single
-new bus; from that point on, it is not used for any further communication until
-the final close().
-
-Each bus will generate a random, 128-bit UUID upon creation. It will be
+must be prefixed with the numeric effective UID of the creator and a dash. This
+is required to avoid namespace clashes between different users. When creating a
+bus, that name that is passed in must be properly formatted, or the kernel will
+refuse creation of the bus. Example: "1047-foobar" is an acceptable name for a
+bus registered by a user with UID 1047. However, "1024-foobar" is not, and
+neither is "foobar". The UID must be provided in the user-namespace of the
+parent domain.
+
+To create a new bus, you need to open the control file of a domain and employ
+the KDBUS_CMD_BUS_MAKE ioctl. The control file descriptor that was used to issue
+KDBUS_CMD_BUS_MAKE must not previously have been used for any other
+control-ioctl and must be kept open for the entire life-time of the created
+bus. Closing it will immediately cleanup the entire bus and all its associated
+resources and endpoints. Every control file descriptor can only be used to
+create a single new bus; from that point on, it is not used for any further
+communication until the final close().
+
+Each bus will generate a random, 128-bit UUID upon creation. This UUID will be
 returned to creators of connections through kdbus_cmd_hello.id128 and can
 be used by userspace to uniquely identify buses, even across different machines
 or containers. The UUID will have its variant bits set to 'DCE', and denote
-version 4 (random).
-
-When creating buses, a variable list of items that must be passed in
-the items array is expected otherwise bus creation will fail.
+version 4 (random). For more details on UUIDs, see
+https://en.wikipedia.org/wiki/Universally_unique_identifier
 
 
 5.3 Endpoints
@@ -306,26 +312,26 @@ to explicitly install policy entries to allow any operation on this endpoint.
 Once KDBUS_CMD_ENDPOINT_MAKE succeeded, this file descriptor will manage the
 newly created endpoint resource. It cannot be used to manage further resources.
 
-Endpoint names may be chosen freely except for one restriction: the name
-must be prefixed with the numeric UID of the creator and a dash. This
-is required to avoid namespace clashes between different users. When
-creating an endpoint the name must be passed in properly formatted, or the
-kernel will refuse creation of the endpoint. Example: "1047-foobar" is an
-OK name for an endpoint registered by a user with UID 1047. However,
-"1024-foobar" is not, and neither is "foobar".
-The UID must be provided in the user-namespace of the parent domain.
+Endpoint names may be chosen freely except for one restriction: the name must
+be prefixed with the numeric effective UID of the creator and a dash. This is
+required to avoid namespace clashes between different users. When creating an
+endpoint, the name that is passed in must be properly formatted or the kernel
+will refuse creation of the endpoint. Example: "1047-foobar" is an acceptable
+name for an endpoint registered by a user with UID 1047. However,
+"1024-my-endpoint" is not, and neither is "my-endpoint". The UID must be
+provided in the user-namespace of the parent domain.
 
 To create connections to a bus, you use KDBUS_CMD_HELLO. See section 6 for
-details. Note that once KDBUS_CMD_HELLO succeeded, this file descriptor manages
-the newly created connection resource. It cannot be used to manage further
-resources.
+details. Note that after a successful KDBUS_CMD_HELLO, this file descriptor
+manages the newly created connection resource. It cannot be used to manage
+further resources.
 
 
 5.4 Creating buses and endpoints
 --------------------------------
 
-KDBUS_CMD_BUS_MAKE, and KDBUS_CMD_ENDPOINT_MAKE take a
-struct kdbus_cmd_make argument.
+KDBUS_CMD_BUS_MAKE and KDBUS_CMD_ENDPOINT_MAKE take a struct kdbus_cmd_make
+argument.
 
 struct kdbus_cmd_make {
   __u64 size;
@@ -342,12 +348,14 @@ struct kdbus_cmd_make {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   struct kdbus_item items[0];
-    A list of items that has specific meanings for KDBUS_CMD_BUS_MAKE
+    A list of items that have specific meanings for KDBUS_CMD_BUS_MAKE
     and KDBUS_CMD_ENDPOINT_MAKE (see above).
 
     Following items are expected for KDBUS_CMD_BUS_MAKE:
@@ -362,7 +370,7 @@ struct kdbus_cmd_make {
       that connections must allow. This item is used as a negotiation
       measure during connection creation. If connections do not satisfy
       the bus requirements, they are not allowed on the bus.
-      If not set, the bus does not require any metadata to be attached,
+      If not set, the bus does not require any metadata to be attached;
       in this case connections are free to set their own attach flags.
 
     KDBUS_ITEM_ATTACH_FLAGS_SEND
@@ -381,30 +389,30 @@ struct kdbus_cmd_make {
 6.1 Connection IDs and well-known connection names
 --------------------------------------------------
 
-Connections are identified by their connection id, internally implemented as a
+Connections are identified by their connection ID, internally implemented as a
 uint64_t counter. The IDs of every newly created bus start at 1, and every new
-connection will increment the counter by 1. The ids are not reused.
+connection will increment the counter by 1. The IDs are not reused.
 
 In higher level tools, the user visible representation of a connection is
-defined by the D-Bus protocol specification as ":1.<id>".
+defined by the D-Bus protocol specification as ":1.<ID>".
 
-Messages with a specific uint64_t destination id are directly delivered to
-the connection with the corresponding id. Messages with the special destination
-id KDBUS_DST_ID_BROADCAST are broadcast messages and are potentially delivered
-to all known connections on the bus; clients interested in broadcast messages
-need to subscribe to the specific messages they are interested, though before
-any broadcast message reaches them.
+Messages with a specific uint64_t destination ID are directly delivered to
+the connection with the corresponding ID. Messages with the special destination
+ID KDBUS_DST_ID_BROADCAST are broadcast messages and are potentially delivered
+to all known connections on the bus. However, in order to receive any broadcast
+messages, clients must subscribe to the specific messages in which they are
+interested.
 
 Messages synthesized and sent directly by the kernel will carry the special
-source id KDBUS_SRC_ID_KERNEL (0).
+source ID KDBUS_SRC_ID_KERNEL (0).
 
-In addition to the unique uint64_t connection id, established connections can
+In addition to the unique uint64_t connection ID, established connections can
 request the ownership of well-known names, under which they can be found and
 addressed by other bus clients. A well-known name is associated with one and
 only one connection at a time. See section 8 on name acquisition and the
 name registry, and the validity of names.
 
-Messages can specify the special destination id 0 and carry a well-known name
+Messages can specify the special destination ID 0 and carry a well-known name
 in the message data. Such a message is delivered to the destination connection
 which owns that well-known name.
 
@@ -461,7 +469,7 @@ which owns that well-known name.
 A connection to a bus is created by opening an endpoint file of a bus and
 becoming an active client with the KDBUS_CMD_HELLO ioctl. Every connected client
 connection has a unique identifier on the bus and can address messages to every
-other connection on the same bus by using the peer's connection id as the
+other connection on the same bus by using the peer's connection ID as the
 destination.
 
 The KDBUS_CMD_HELLO ioctl takes the following struct as argument.
@@ -475,55 +483,56 @@ struct kdbus_cmd_hello {
 
     KDBUS_HELLO_ACCEPT_FD
       When this flag is set, the connection can be sent file descriptors
-      as message payload. If it's not set, any attempt of doing so will
-      result in -ECOMM on the sender's side.
+      as message payload. If it's not set, an attempt to send file descriptors
+      results in -ECOMM on the sender's side.
 
     KDBUS_HELLO_ACTIVATOR
       Make this connection an activator (see below). With this bit set,
-      an item of type KDBUS_ITEM_NAME has to be attached which describes
+      an item of type KDBUS_ITEM_NAME has to be attached. This item describes
       the well-known name this connection should be an activator for.
 
     KDBUS_HELLO_POLICY_HOLDER
       Make this connection a policy holder (see below). With this bit set,
-      an item of type KDBUS_ITEM_NAME has to be attached which describes
+      an item of type KDBUS_ITEM_NAME has to be attached. This item describes
       the well-known name this connection should hold a policy for.
 
     KDBUS_HELLO_MONITOR
-      Make this connection an eaves-dropping connection. See section 6.8 for
+      Make this connection an eavesdropping connection. See section 6.8 for
       more information.
 
-To also receive broadcast messages,
-      the connection has to upload appropriate matches as well.
-      This flag is only valid for privileged bus connections.
+      To also receive broadcast messages, the connection has to upload
+      appropriate matches as well. This flag is only valid for privileged bus
+      connections.
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   __u64 attach_flags_send;
       Set the bits for metadata this connection permits to be sent to the
       receiving peer. Only metadata items that are both allowed to be sent by
       the sender and that are requested by the receiver will effectively be
-      attached to the message eventually. Note, however, that the bus may
-      optionally enforce some of those bits to be set. If the match fails,
-      -ECONNREFUSED will be returned. In either case, this field will be set
-      to the mask of metadata items that are enforced by the bus. The
-      KDBUS_FLAGS_KERNEL bit will as well be set.
+      attached to the message. Note, however, that the bus may optionally
+      require some of those bits to be set. If the match fails, -ECONNREFUSED
+      will be returned. In either case, this field will be set to the mask of
+      metadata items that are enforced by the bus. The KDBUS_FLAGS_KERNEL bit
+      will as well be set.
 
   __u64 attach_flags_recv;
       Request the attachment of metadata for each message received by this
-      connection. The metadata actually attached may actually augment the list
-      of requested items. See section 13 for more details.
+      connection. See section 13 for more details.
 
   __u64 bus_flags;
       Upon successful completion of the ioctl, this member will contain the
       flags of the bus it connected to.
 
-  __u64 id;
+  __u64 ID;
       Upon successful completion of the ioctl, this member will contain the
-      id of the new connection.
+      ID of the new connection.
 
   __u64 pool_size;
       The size of the communication pool, in bytes. The pool can be accessed
@@ -536,14 +545,14 @@ To also receive broadcast messages,
 
   __u8 id128[16];
       Upon successful completion of the ioctl, this member will contain the
-      128 bit wide UUID of the connected bus.
+      128-bit UUID of the connected bus.
 
   struct kdbus_item items[0];
-      Variable list of items to add optional additional information. The
+      Variable list of items containing optional additional information. The
       following items are currently expected/valid:
 
       KDBUS_ITEM_CONN_DESCRIPTION
-        Contains a string to describes this connection's name, so it can be
+        Contains a string that describes this connection's name, so it can be
         identified later.
 
       KDBUS_ITEM_NAME
@@ -584,8 +593,8 @@ are removed once it terminates. Such a policy connection type can be used to
 deploy restrictions for names that are not yet active on the bus. A policy
 holder connection cannot be used to send any message.
 
-The creation of activator, policy holder or monitor connections is an operation
-restricted to privileged users on the bus (see section "Terminology").
+The creation of activator, policy holder or eavesdropping connections is an
+operation restricted to privileged users on the bus (see section "Terminology").
 
 
 6.4 Retrieving information on a connection
@@ -597,25 +606,26 @@ following struct:
 
 struct kdbus_cmd_info {
   __u64 size;
-    The overall size of the struct, including the name with its 0-byte string
-    terminator.
+    The overall size of the struct, including the null-terminated name string.
 
   __u64 flags;
-    Specify which metadata items should be attached to the answer.
+    Specifies which metadata items should be attached to the answer.
     See section 13 for more details.
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
-  __u64 id;
-    The connection's numerical ID to retrieve information for. If set to
-    non-zero value, the 'name' field is ignored.
+  __u64 ID;
+    The numerical ID of the connection for which information is to be retrieved.
+    If set to a non-zero value, the 'name' field is ignored.
 
   __u64 offset;
-    When the ioctl returns, this value will yield the offset of the connection
+    When the ioctl returns, this field will contain the offset of the connection
     information inside the caller's pool.
 
   __u64 info_size;
@@ -624,7 +634,7 @@ struct kdbus_cmd_info {
 
   struct kdbus_item items[0];
     The optional item list, containing the well-known name to look up as
-    a KDBUS_ITEM_OWNED_NAME. Only required if the 'id' field is set to 0.
+    a KDBUS_ITEM_OWNED_NAME. Only required if the 'ID' field is set to 0.
     Items of other types are rejected, and the ioctl will fail with -EINVAL.
 };
 
@@ -635,16 +645,15 @@ struct kdbus_info {
   __u64 size;
     The overall size of the struct, including all its items.
 
-  __u64 id;
+  __u64 ID;
     The connection's unique ID.
 
   __u64 flags;
     The connection's flags as specified when it was created.
 
   struct kdbus_item items[0];
-    Depending on the 'flags' field in struct kdbus_cmd_info, items of
-    types KDBUS_ITEM_OWNED_NAME and KDBUS_ITEM_CONN_DESCRIPTION are followed
-    here.
+    Depending on the 'flags' field in struct kdbus_cmd_info, items of types
+    KDBUS_ITEM_OWNED_NAME and KDBUS_ITEM_CONN_DESCRIPTION follow here.
 };
 
 Once the caller is finished with parsing the return buffer, it needs to call
@@ -669,14 +678,15 @@ struct kdbus_info {
   __u64 size;
     The overall size of the struct, including all its items.
 
-  __u64 id;
+  __u64 ID;
     The bus ID
 
   __u64 flags;
-    The bus flags as specified when it was created.
+    The bus flags as specified when the bus was created.
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   struct kdbus_item items[0];
     Metadata information is stored in items here. The item list contains
@@ -704,9 +714,11 @@ struct kdbus_cmd_update {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   struct kdbus_item items[0];
     Items to describe the connection details to be updated. The following item
@@ -735,9 +747,9 @@ A connection can be terminated by simply closing its file descriptor. All
 pending incoming messages will be discarded, and the memory in the pool will
 be freed.
 
-An alternative way of closing down a connection is calling the KDBUS_CMD_BYEBYE
-ioctl on it, which will only succeed if the message queue of the connection is
-empty at the time of closing, otherwise, -EBUSY is returned.
+An alternative way of closing down a connection is via the KDBUS_CMD_BYEBYE
+ioctl. This ioctly will succeed only if the message queue of the connection is
+empty at the time of closing; otherwise, -EBUSY is returned.
 
 When this ioctl returns successfully, the connection has been terminated and
 won't accept any new messages from remote peers. This way, a connection can
@@ -807,15 +819,15 @@ struct kdbus_cmd_send {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call of
-    KDBUS_CMD_SEND.
+    KDBUS_CMD_SEND. See section 3.2 for more details.
 
   __u64 kernel_msg_flags;
     Valid bits for message flags, returned by the kernel upon each call of
     KDBUS_CMD_SEND.
 
   __u64 return_flags;
-    Kernel-provided flags, returning non-fatal errors that occurred during
-    send. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   __u64 msg_address;
     Userspace has to provide a pointer to a message (struct kdbus_msg) to send.
@@ -847,7 +859,7 @@ struct kdbus_msg {
 
   __u64 flags;
     KDBUS_MSG_EXPECT_REPLY
-      Expect a reply from the remote peer to this message. With this bit set,
+      Expect a reply to this message from the remote peer. With this bit set,
       the timeout_ns field must be set to a non-zero number of nanoseconds in
       which the receiving peer is expected to reply. If such a reply is not
       received in time, the sender will be notified with a timeout message
@@ -889,7 +901,7 @@ struct kdbus_msg {
     Type of the payload in the actual data records. Currently, only
     KDBUS_PAYLOAD_DBUS is accepted as input value of this field. When
     receiving messages that are generated by the kernel (notifications),
-    this field will yield KDBUS_PAYLOAD_KERNEL.
+    this field will contain KDBUS_PAYLOAD_KERNEL.
 
   __u64 cookie;
     Cookie of this message, for later recognition. Also, when replying
@@ -941,8 +953,8 @@ The layout of a message is shown below.
   | +---------------------------------------------------------------------+ |
   | | Header                                                              | |
   | | size:          overall message size, including the data records     | |
-  | | destination:   connection id of the receiver                        | |
-  | | source:        connection id of the sender (set by kernel)          | |
+  | | destination:   connection ID of the receiver                        | |
+  | | source:        connection ID of the sender (set by kernel)          | |
   | | payload_type:  "DBusDBus" textual identifier stored as uint64_t     | |
   | +---------------------------------------------------------------------+ |
   | +---------------------------------------------------------------------+ |
@@ -980,9 +992,9 @@ pool is internally backed by a shared memory file which can be mmap()ed by
 the receiver.
 
 KDBUS_MSG_PAYLOAD_VEC:
-  Messages are directly copied by the sending process into the receiver's pool,
-  that 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.
+  Messages are directly copied by the sending process into the receiver's pool.
+  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.
 
 KDBUS_MSG_PAYLOAD_MEMFD:
   Messages can reference memfd files which contain the data.
@@ -996,12 +1008,13 @@ KDBUS_MSG_PAYLOAD_MEMFD:
   be passed as zero-copy from one process to another, read-only, shared between
   the peers.
 
-The sender must not make any assumptions on the type how data is received by the
-remote peer. The kernel is free to re-pack multiple VEC and MEMFD payloads. For
-instance, the kernel may decide to merge multiple VECs into a single VEC, inline
-MEMFD payloads into memory or merge all passed VECs into a single MEMFD.
-However, the kernel preserves the order of passed data. This means, the order of
-all VEC and MEMFD items is not changed in respect to each other.
+The sender must not make any assumptions on the type in which data is received
+by the remote peer. The kernel is free to re-pack multiple VEC and MEMFD
+payloads. For instance, the kernel may decide to merge multiple VECs into a
+single VEC, inline MEMFD payloads into memory or merge all passed VECs into a
+single MEMFD. However, the kernel preserves the order of passed data. This
+means that the order of all VEC and MEMFD items is not changed in respect to
+each other.
 
 In other words: All passed VEC and MEMFD data payloads are treated as a single
 stream of data that may be received by the remote peer in a different set of
@@ -1012,8 +1025,8 @@ hunks than it was sent as.
 ----------------------
 
 Messages are received by the client with the KDBUS_CMD_RECV ioctl. The endpoint
-file of the bus supports poll() to wake up the receiving process when new
-messages are queued up to be received.
+file of the bus supports poll/epoll/select() to wake up the receiving process
+when new messages are queued up to be received.
 
 With the KDBUS_CMD_RECV ioctl, a struct kdbus_cmd_recv is used.
 
@@ -1038,10 +1051,11 @@ struct kdbus_cmd_recv {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Kernel-provided flags, returning non-fatal errors that occurred during
-    send. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   __s64 priority;
     With KDBUS_RECV_USE_PRIORITY set in flags, receive the next message in
@@ -1057,7 +1071,8 @@ struct kdbus_cmd_recv {
    Embedded struct to be filled when the command succeeded (see below).
 
   struct kdbus_item items[0];
-    Items to specify further details for the receive command. Currently unused.
+    Items to specify further details for the receive command. Currently unused,
+    and all items will be rejected with -EINVAL,
 };
 
 Both 'struct kdbus_cmd_recv' and 'struct kdbus_cmd_send' embed 'struct
@@ -1088,14 +1103,14 @@ struct kdbus_msg_info {
         installed will be set to -1.
 };
 
-Unless KDBUS_RECV_DROP was passed, and given that the ioctl succeeded, the
+Unless KDBUS_RECV_DROP was passed after a successful KDBUS_CMD_RECV ioctl, the
 offset field contains the location of the new message inside the receiver's
 pool. The message is stored as struct kdbus_msg at this offset, and can be
 interpreted with the semantics described above.
 
 Also, if the connection allowed for file descriptor to be passed
 (KDBUS_HELLO_ACCEPT_FD), and if the message contained any, they will be
-installed into the receiving process after the KDBUS_CMD_RECV ioctl returns.
+installed into the receiving process when the KDBUS_CMD_RECV ioctl is called.
 The receiving task is obliged to close all of them appropriately. If
 KDBUS_RECV_PEEK is set, no file descriptors are installed. This allows for
 peeking at a message and dropping it via KDBUS_RECV_DROP, without installing
@@ -1119,7 +1134,7 @@ All of the below is subject to policy rules for SEE and OWN permissions.
 8.1 Name validity
 -----------------
 
-A name has to comply to the following rules to be considered valid:
+A name has to comply with the following rules to be considered valid:
 
  - The name has two or more elements separated by a period ('.') character
  - All elements must contain at least one character
@@ -1139,8 +1154,7 @@ following data structure.
 
 struct kdbus_cmd_name {
   __u64 size;
-    The overall size of this struct, including the name with its 0-byte string
-    terminator.
+    The overall size of this struct, including the null-terminated name string.
 
   __u64 flags;
     Flags to control details in the name acquisition.
@@ -1165,6 +1179,7 @@ struct kdbus_cmd_name {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
     Flags returned by the kernel. Currently unused.
@@ -1190,17 +1205,18 @@ acquisition call, but with slightly different field usage.
 
 struct kdbus_cmd_name {
   __u64 size;
-    The overall size of this struct, including the name with its 0-byte string
-    terminator.
+    The overall size of this struct, including the null-terminated name string.
 
   __u64 flags;
-    Flags to the command. Currently unused.
+    Flags to the command. Currently unused and must be zero.
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   struct kdbus_item items[0];
     Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is
@@ -1236,9 +1252,11 @@ struct kdbus_cmd_name_list {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   __u64 offset;
     When the ioctl returns successfully, the offset to the name registry dump
@@ -1251,8 +1269,7 @@ information. The fields inside that struct kdbus_cmd_name is described next.
 
 struct kdbus_name_info {
   __u64 size;
-    The overall size of this struct, including the name with its 0-byte string
-    terminator.
+    The overall size of this struct, including the null-terminated name string.
 
   __u64 owner_id;
     The owning connection's unique ID.
@@ -1379,7 +1396,7 @@ To receive kernel generated notifications (see section 9), a connection must
 install special match rules that are different from the bloom filter matches
 described in the section above. They can be filtered by a sender connection's
 ID, by one of the name the sender connection owns at the time of sending the
-message, or by type of the notification (id/name add/remove/change).
+message, or by the type of the notification (ID/name add/remove/change).
 
 10.3 Adding a match
 -------------------
@@ -1389,10 +1406,10 @@ of the struct described below.
 
 Note that each of the items attached to this command will internally create
 one match 'rule', and the collection of them, which is submitted as one block
-via the ioctl is called a 'match'. To allow a message to pass, all rules of a
+via the ioctl, is called a 'match'. To allow a message to pass, all rules of a
 match have to be satisfied. Hence, adding more items to the command will only
 narrow the possibility of a match to effectively let the message pass, and will
-cause the connection's user space process to wake up less likely.
+decrease the chance that the connection's userspace process wil be woken up.
 
 Multiple matches can be installed per connection. As long as one of it has a
 set of rules which allows the message to pass, this one will be decisive.
@@ -1414,9 +1431,11 @@ struct kdbus_cmd_match {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   struct kdbus_item items[0];
     Items to define the actual rules of the matches. The following item types
@@ -1429,7 +1448,7 @@ struct kdbus_cmd_match {
       See section 10.4 for more information.
 
     KDBUS_ITEM_NAME
-      Specify a name that a sending connection must own at a time of sending
+      Specify a name that a sending connection must own at the time of sending
       a broadcast message in order to match this rule.
 
     KDBUS_ITEM_ID
@@ -1449,7 +1468,7 @@ struct kdbus_cmd_match {
       These items request delivery of broadcast messages that are generated
       when a connection is created or terminated. struct kdbus_notify_id_change
       is used to store the actual match information. This item can be used to
-      monitor one particular connection ID, or, when the id field is set to
+      monitor one particular connection ID, or, when the ID field is set to
       KDBUS_MATCH_ID_ANY, all of them.
 
     Items of other types are rejected, and the ioctl will fail with -EINVAL.
@@ -1483,7 +1502,7 @@ Masks are entities that are always passed to the kernel as part of a match
 signals, with an item of type KDBUS_ITEM_BLOOM_FILTER.
 
 For a filter to match, all its bits have to be set in the match mask as well.
-For example, consider a bus has a bloom size of 8 bytes, and the following
+For example, consider a bus that has a bloom size of 8 bytes, and the following
 mask/filter combinations:
 
     filter  0x0101010101010101
@@ -1501,7 +1520,7 @@ mask/filter combinations:
 Hence, in order to catch all messages, a mask filled with 0xff bytes can be
 installed as a wildcard match rule.
 
-Uploaded matches may contain multiple masks, each of which in the size of the
+Uploaded matches may contain multiple masks, which have are as large as the
 bloom size defined by the bus. Each block of a mask is called a 'generation',
 starting at index 0.
 
@@ -1521,7 +1540,7 @@ differently.
 struct kdbus_cmd_match {
   __u64 size;
     The overall size of the struct. As it has no items in this use case, the
-    value should yield 16.
+    value should contain 16.
 
   __u64 cookie;
     The cookie of the match, as it was passed when the match was added.
@@ -1532,9 +1551,11 @@ struct kdbus_cmd_match {
 
   __u64 kernel_flags;
     Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
 
   __u64 return_flags;
-    Flags returned by the kernel. Currently unused.
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
 
   struct kdbus_item items[0];
     Unused und not allowed for this use case.
@@ -1545,8 +1566,8 @@ struct kdbus_cmd_match {
 ===============================================================================
 
 A policy databases restrict the possibilities of connections to own, see and
-talk to well-known names. It can be associated with a bus (through a policy
-holder connection) or a custom endpoint.
+talk to well-known names. A policy can be associated with a bus (through a
+policy holder connection) or a custom endpoint.
 
 See section 8.1 for more details on the validity of well-known names.
 
@@ -1566,13 +1587,13 @@ struct kdbus_policy_access {
     One of the following.
 
     KDBUS_POLICY_ACCESS_USER
-      Grant access to a user with the uid stored in the 'id' field.
+      Grant access to a user with the UID stored in the 'ID' field.
 
     KDBUS_POLICY_ACCESS_GROUP
-      Grant access to a user with the gid stored in the 'id' field.
+      Grant access to a user with the GID stored in the 'ID' field.
 
     KDBUS_POLICY_ACCESS_WORLD
-      Grant access to everyone. The 'id' field is ignored.
+      Grant access to everyone. The 'ID' field is ignored.
 
   __u64 access;	/* OWN, TALK, SEE */
     The access to grant.
@@ -1586,9 +1607,9 @@ struct kdbus_policy_access {
     KDBUS_POLICY_OWN
       Allow the name to be owned.
 
-  __u64 id;
-    For KDBUS_POLICY_ACCESS_USER, stores the uid.
-    For KDBUS_POLICY_ACCESS_GROUP, stores the gid.
+  __u64 ID;
+    For KDBUS_POLICY_ACCESS_USER, stores the UID.
+    For KDBUS_POLICY_ACCESS_GROUP, stores the GID.
 };
 
 Policies are set through KDBUS_CMD_HELLO (when creating a policy holder
@@ -1604,20 +1625,19 @@ KDBUS_ITEM_POLICY_ACCESS. For this transport, the following rules apply.
     KDBUS_ITEM_POLICY_ACCESS items
   * An arbitrary number of groups of names and access levels can be passed
 
-uids and gids are internally always stored in the kernel's view of global ids,
+UIDs and GIDs are internally always stored in the kernel's view of global IDs,
 and are translated back and forth on the ioctl level accordingly.
 
 
 11.2 Wildcard names
 -------------------
 
-Policy holder connections may upload names that contain the wild card suffix
+Policy holder connections may upload names that contain the wildcard suffix
 (".*"). That way, a policy can be uploaded that is effective for every
 well-known name that extends the provided name by exactly one more level.
 
-For example, if an item of a set up uploaded policy rules contains the name
-"foo.bar.*", both "foo.bar.baz" and "foo.bar.bazbaz" are valid, but
-"foo.bar.baz.baz" is not.
+For example, the name "foo.bar.*" allowes both "foo.bar.baz" and
+"foo.bar.bazbaz" are valid, but not "foo.bar.baz.baz".
 
 This allows connections to take control over multiple names that the policy
 holder doesn't need to know about when uploading the policy.
@@ -1631,18 +1651,18 @@ Such wildcard entries are not allowed for custom endpoints.
 For example, a set of policy rules may look like this:
 
   KDBUS_ITEM_NAME: str='org.foo.bar'
-  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, id=1000
-  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, id=1001
+  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
+  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
   KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE
   KDBUS_ITEM_NAME: str='org.blah.baz'
-  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, id=0
+  KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
   KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
 
-That means that 'org.foo.bar' may only be owned by uid 1000, but every user on
-the bus is allowed to see the name. However, only uid 1001 may actually send
+That means that 'org.foo.bar' may only be owned by UID 1000, but every user on
+the bus is allowed to see the name. However, only UID 1001 may actually send
 a message to the connection and receive a reply from it.
 
-The second rule allows 'org.blah.baz' to be owned by uid 0 only, but every user
+The second rule allows 'org.blah.baz' to be owned by UID 0 only, but every user
 may talk to it.
 
 
@@ -1663,8 +1683,8 @@ receive the broadcast.
 
 If a policy database exists for a bus (because a policy holder created one on
 demand) or for a custom endpoint (which always has one), each one is consulted
-during name registry listing, name owning or message delivery. If either one
-fails, the operation is failed with -EPERM.
+to allow name registry listing, owning a well-known name and message delivery.
+If either one fails, the operation is failed with -EPERM.
 
 For best practices, connections that own names with a restricted TALK
 access should not install matches. This avoids cases where the sent
@@ -1713,10 +1733,9 @@ The pool is written to by the kernel when one of the following ioctls is issued:
 
 The offsets returned by either one of the aforementioned ioctls describe offsets
 inside the pool. In order to make the slice available for subsequent calls,
-KDBUS_CMD_FREE has to be called on the offset.
+KDBUS_CMD_FREE has to be called on the offset (see below).
 
-To access the memory, the caller is expected to mmap() it to its task, like
-this:
+To access the memory, the caller is expected to mmap() it, like this:
 
   /*
    * POOL_SIZE has to be a multiple of PAGE_SIZE, and it must match the
@@ -1731,6 +1750,38 @@ be mapped. The length of the response is returned by the kernel along with the
 offset for each of the ioctls listed above.
 
 
+12.1 Freeing pool slices
+------------------------
+
+The KDBUS_CMD_FREE is used to free a slice inside the pool, described an offset
+that was returned in an 'offset' field of another ioctl struct. The command
+takes a struct kdbus_cmd_free as argument:
+
+struct kdbus_cmd_free {
+  __u64 size;
+    The overall size of this struct, including all its items.
+
+  __u64 offset;
+    The offset to free, as returned by other ioctls that allocated memory to
+    for returned information.
+
+  __u64 flags;
+    Flags to change the behavior of the command. Currently unused.
+
+  __u64 kernel_flags;
+    Valid flags for this command, returned by the kernel upon each call.
+    See section 3.2 for more details.
+
+  __u64 return_flags;
+    Flags returned by the kernel. Currently unused and always set to zero by
+    the kernel.
+
+  struct kdbus_item items[0];
+    Items to specify further details for the receive command. Currently unused.
+    All items will be rejected with -EINVAL.
+};
+
+
 13. Metadata
 ===============================================================================
 
@@ -1744,11 +1795,11 @@ Metadata is collected in the following circumstances:
 
   * When a bus is created (KDBUS_CMD_MAKE), information about the calling task
     is collected. This data is returned by the kernel via the
-    KDBUS_CMD_BUS_CREATOR_INFO call-
+    KDBUS_CMD_BUS_CREATOR_INFO call.
 
   * When a connection is created (KDBUS_CMD_HELLO), information about the
     calling task is collected. Alternatively, a privileged connection may
-    provide 'faked' information about credentials, PIDs and a security labels
+    provide 'faked' information about credentials, PIDs and security labels
     which will be taken instead. This data is returned by the kernel as
     information on a connection (KDBUS_CMD_CONN_INFO).
 
@@ -1813,7 +1864,7 @@ The following attach flags are currently supported.
 
   KDBUS_ATTACH_TID_COMM [*]
     Attaches an items of type KDBUS_ITEM_TID_COMM, transporting the sending
-    task's 'comm', for the tid.  The string is stored in kdbus_item.str.
+    task's 'comm', for the TID.  The string is stored in kdbus_item.str.
 
   KDBUS_ATTACH_PID_COMM [*]
     Attaches an items of type KDBUS_ITEM_PID_COMM, transporting the sending
@@ -1882,21 +1933,22 @@ For all ioctls:
 
   -ENOMEM	The kernel memory is exhausted
   -ENOTTY	Illegal ioctl command issued for the file descriptor
-  -ENOSYS	The requested functionality is not available
   -EINVAL	Unsupported item attached to command
 
 For all ioctls that carry a struct as payload:
 
   -EFAULT	The supplied data pointer was not 64-bit aligned, or was
 		inaccessible from the kernel side.
-  -EINVAL	The size inside the supplied struct was smaller than expected
+  -EINVAL	The size inside the supplied struct was smaller than expected,
+		resulting in an invalid set of information to perform the
+		requrest.
   -EMSGSIZE	The size inside the supplied struct was bigger than expected
   -ENAMETOOLONG	A supplied name is larger than the allowed maximum size
 
 For KDBUS_CMD_BUS_MAKE:
 
   -EINVAL	The flags supplied in the kdbus_cmd_make struct are invalid or
-		the supplied name does not start with the current uid and a '-'
+		the supplied name does not start with the current UID and a '-'
   -EEXIST	A bus of that name already exists
   -ESHUTDOWN	The domain for the bus is already shut down
   -EMFILE	The maximum number of buses for the current user is exhausted
@@ -1919,7 +1971,7 @@ For KDBUS_CMD_HELLO:
   -EPERM	An KDBUS_ITEM_CREDS items was supplied, but the current user is
 		not privileged
   -ESHUTDOWN	The bus has already been shut down
-  -EMFILE	The maximum number of connection on the bus has been reached
+  -EMFILE	The maximum number of connections on the bus has been reached
   -EOPNOTSUPP	The endpoint does not support the connection flags
 		supplied in the kdbus_cmd_hello struct
 
@@ -1937,9 +1989,9 @@ For KDBUS_CMD_SEND:
 		KDBUS_MSG_EXPECT_REPLY was set without timeout or cookie
 		values, KDBUS_MSG_SYNC_REPLY was set without
 		KDBUS_MSG_EXPECT_REPLY, an invalid item was supplied,
-		src_id was != 0 and different from the current connection's ID,
-		a supplied memfd had a size of 0, a string was not properly
-		null-terminated
+		src_id was non-zero and was different from the current
+		connection's ID, a supplied memfd had a size of 0, a string was
+		not properly null-terminated
   -ENOTUNIQ	The supplied destination is KDBUS_DST_ID_BROADCAST, a file
 		descriptor was passed, KDBUS_MSG_EXPECT_REPLY was set,
 		or a timeout was given for a broadcast message
@@ -1992,9 +2044,10 @@ For KDBUS_CMD_RECV:
 For KDBUS_CMD_FREE:
 
   -ENXIO	No pool slice found at given offset
-  -EINVAL	Invalid flags provided, the offset is valid, but the user is
-		not allowed to free the slice. This happens, for example, if
-		the offset was retrieved with KDBUS_RECV_PEEK.
+  -EINVAL	Invalid flags provided
+  -EINVAL	The offset is valid, but the user is not allowed to free the
+		slice. This happens, for example, if the offset was retrieved
+		with KDBUS_RECV_PEEK.
 
 For KDBUS_CMD_NAME_ACQUIRE: