kdbus.message kdbus.message 7 kdbus.message kdbus message A kdbus message is used to exchange information between two connections on a bus, or to transport notifications from the kernel to one or many connections. This document describes the layout of messages, how payload is added to them and how they are sent and received. The layout of a message is shown below. +-------------------------------------------------------------------------+ | Message | | +---------------------------------------------------------------------+ | | | Header | | | | size: overall message size, including the data records | | | | destination: connection ID of the receiver | | | | source: connection ID of the sender (set by kernel) | | | | payload_type: "DBusDBus" textual identifier stored as uint64_t | | | +---------------------------------------------------------------------+ | | +---------------------------------------------------------------------+ | | | Data Record | | | | size: overall record size (without padding) | | | | type: type of data | | | | data: reference to data (address or file descriptor) | | | +---------------------------------------------------------------------+ | | +---------------------------------------------------------------------+ | | | padding bytes to the next 8 byte alignment | | | +---------------------------------------------------------------------+ | | +---------------------------------------------------------------------+ | | | Data Record | | | | size: overall record size (without padding) | | | | ... | | | +---------------------------------------------------------------------+ | | +---------------------------------------------------------------------+ | | | padding bytes to the next 8 byte alignment | | | +---------------------------------------------------------------------+ | | +---------------------------------------------------------------------+ | | | Data Record | | | | size: overall record size | | | | ... | | | +---------------------------------------------------------------------+ | | ... further data records ... | +-------------------------------------------------------------------------+ When connecting to the bus, receivers request a memory pool of a given size, large enough to carry all backlog of data enqueued for the connection. The pool is internally backed by a shared memory file which can be mmap()ed by the receiver. See kdbus.pool 7 for more information. Message payload must be described in items attached to a message when it is sent. A receiver can access the payload by looking at the items that are attached to a message in its pool. The following items are used. KDBUS_ITEM_PAYLOAD_VEC This item references a piece of memory on the sender side which is directly copied 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. This item is never found in a message received by a connection. KDBUS_ITEM_PAYLOAD_OFF This item is attached to messages on the receiving side and points to a memory area inside the receiver's pool. The offset variable in the item denotes the memory location relative to the message itself. KDBUS_ITEM_PAYLOAD_MEMFD Messages can reference memfd files which contain the data. memfd files are tmpfs-backed files that allow sealing of the content of the file, which prevents all writable access to the file content. Only memfds that have (F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL) set are accepted as payload data, which enforces reliable passing of data. The receiver can assume that neither the sender nor anyone else can alter the content after the message is sent. If those seals are not set on the memfd, the ioctl will fail with -1, and errno will be set to ETXTBUSY. KDBUS_ITEM_FDS Messages can transport regular file descriptors via KDBUS_ITEM_FDS. This item carries an array of int values in item.fd. The maximum number of file descriptors in the item is 253, and only one item of this type is accepted per message. All passed values must be valid file descriptors; the open count of each file descriptors is increased by installing it to the receiver's task. This item can only be used for directed messages, not for broadcasts, and only to remote peers that have opted-in for receiving file descriptors at connection time (KDBUS_HELLO_ACCEPT_FD). 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 KDBUS_ITEM_PAYLOAD_VEC and KDBUS_ITEM_PAYLOAD_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 chunks than it was sent as. Messages are passed to the kernel with the KDBUS_CMD_SEND ioctl. Depending on the destination address of the message, the kernel delivers the message to the specific destination connection, or to some subset of all connections on the same bus. Sending messages across buses is not possible. Messages are always queued in the memory pool of the destination connection (see above). The KDBUS_CMD_SEND ioctl uses a struct kdbus_cmd_send to describe the message transfer. struct kdbus_cmd_send { __u64 size; __u64 flags; __u64 return_flags; __u64 msg_address; struct kdbus_msg_info reply; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags for message delivery KDBUS_SEND_SYNC_REPLY By default, all calls to kdbus are considered asynchronous, non-blocking. However, as there are many use cases that need to wait for a remote peer to answer a method call, there's a way to send a message and wait for a reply in a synchronous fashion. This is what the KDBUS_SEND_SYNC_REPLY controls. The KDBUS_CMD_SEND ioctl will block until the reply has arrived, the timeout limit is reached, in case the remote connection was shut down, or if interrupted by a signal before any reply; see signal 7 . The offset of the reply message in the sender's pool is stored in reply when the ioctl has returned without error. Hence, there is no need for another KDBUS_CMD_RECV ioctl or anything else to receive the reply. KDBUS_FLAG_NEGOTIATE Request a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will fail with -1, errno is set to EPROTO. Once the ioctl returned, the flags field will have all bits set that the kernel recognizes as valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. msg_address In this field, users have to provide a pointer to a message (struct kdbus_msg) to send. See below for a detailed description. reply Only used for synchronous replies. See description of struct kdbus_cmd_recv for more details. items The following items are currently recognized. KDBUS_ITEM_CANCEL_FD When this optional item is passed in, and the call is executed as SYNC call, the passed in file descriptor can be used as alternative cancellation point. The kernel will call poll 2 on this file descriptor, and once it reports any incoming bytes, the blocking send operation will be canceled; the blocking, synchronous ioctl call will return -1, and errno will be set to ECANCELED. Any type of file descriptor on which poll 2 can be called on can be used as payload to this item; for example, an eventfd can be used for this purpose, see eventfd 2 . For asynchronous message sending, this item is allowed but ignored. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. The message referenced by the msg_address above has the following layout. struct kdbus_msg { __u64 size; __u64 flags; __s64 priority; __u64 dst_id; __u64 src_id; __u64 payload_type; __u64 cookie; __u64 timeout_ns; __u64 cookie_reply; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags to describe message details. KDBUS_MSG_EXPECT_REPLY 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 (see below). The value must be an absolute value, in nanoseconds and based on CLOCK_MONOTONIC. For a message to be accepted as reply, it must be a direct message to the original sender (not a broadcast and not a signal message), and its kdbus_msg.cookie_reply must match the previous message's kdbus_msg.cookie. Expected replies also temporarily open the policy of the sending connection, so the other peer is allowed to respond within the given time window. KDBUS_MSG_NO_AUTO_START By default, when a message is sent to an activator connection, the activator is notified and will start an implementer. This flag inhibits that behavior. With this bit set, and the remote being an activator, the ioctl will fail with errno set to EADDRNOTAVAIL. KDBUS_FLAG_NEGOTIATE Requests a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will return 0, and the flags field will have all bits set that are valid for this command. The KDBUS_FLAG_NEGOTIATE bit will be cleared by the operation. priority The priority of this message. Receiving messages (see below) may optionally be constrained to messages of a minimal priority. This allows for use cases where timing critical data is interleaved with control data on the same connection. If unused, the priority field should be set to 0. dst_id The numeric ID of the destination connection, or KDBUS_DST_ID_BROADCAST (~0ULL) to address every peer on the bus, or KDBUS_DST_ID_NAME (0) to look it up dynamically from the bus' name registry. In the latter case, an item of type KDBUS_ITEM_DST_NAME is mandatory. Also see kdbus.name 7 . src_id Upon return of the ioctl, this member will contain the sending connection's numerical ID. Should be 0 at send time. payload_type 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 contain KDBUS_PAYLOAD_KERNEL. cookie Cookie of this message, for later recognition. Also, when replying to a message (see above), the cookie_reply field must match this value. timeout_ns If the message sent requires a reply from the remote peer (see above), this field contains the timeout in absolute nanoseconds based on CLOCK_MONOTONIC. Also see clock_gettime 2 . cookie_reply If the message sent is a reply to another message, this field must match the cookie of the formerly received message. items A dynamically sized list of items to contain additional information. The following items are expected/valid: KDBUS_ITEM_PAYLOAD_VEC KDBUS_ITEM_PAYLOAD_MEMFD KDBUS_ITEM_FDS Actual data records containing the payload. See section "Message payload". KDBUS_ITEM_BLOOM_FILTER Bloom filter for matches (see below). KDBUS_ITEM_DST_NAME Well-known name to send this message to. Required if dst_id is set to KDBUS_DST_ID_NAME. If a connection holding the given name can't be found, the ioctl will fail with errno set to ESRCH is returned. For messages to a unique name (ID), this item is optional. If present, the kernel will make sure the name owner matches the given unique name. This allows programs to tie the message sending to the condition that a name is currently owned by a certain unique name. The message will be augmented by the requested metadata items when queued into the receiver's pool. See kdbus.connection 7 and kdbus.item 7 for more information on metadata. Messages are received by the client with the KDBUS_CMD_RECV ioctl. The endpoint file of the bus supports poll()/epoll()/select(); when new messages are available on the connection's file descriptor, POLLIN is reported. For compatibility reasons, POLLOUT is always reported as well. Note, however, that the latter does not guarantee that a message can in fact be sent, as this depends on how many pending messages the receiver has in its pool. With the KDBUS_CMD_RECV ioctl, a struct kdbus_cmd_recv is used. struct kdbus_cmd_recv { __u64 size; __u64 flags; __u64 return_flags; __s64 priority; __u64 dropped_msgs; struct kdbus_msg_info msg; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags Flags to control the receive command. KDBUS_RECV_PEEK Just return the location of the next message. Do not install file descriptors or anything else. This is usually used to determine the sender of the next queued message. KDBUS_RECV_DROP Drop the next message without doing anything else with it, and free the pool slice. This a short-cut for KDBUS_RECV_PEEK and KDBUS_CMD_FREE. KDBUS_RECV_USE_PRIORITY Dequeue the messages ordered by their priority, and filtering them with the priority field (see below). KDBUS_FLAG_NEGOTIATE Request a set of valid flags for this ioctl. When this bit is set, no action is taken; the ioctl will fail with -1, errno is set to EPROTO. Once the ioctl returned, the flags field will have all bits set that the kernel recognizes as valid for this command. return_flags Flags returned by the kernel. If the dropped_msgs field is non-zero, KDBUS_RECV_RETURN_DROPPED_MSGS is set. If a file descriptor could not be installed, the KDBUS_RECV_RETURN_INCOMPLETE_FDS flag is set. priority With KDBUS_RECV_USE_PRIORITY set in flags, messages will be dequeued ordered by their priority, starting with the highest value. Also, messages will be filtered by the value given in this field, so the returned message will at least have the requested priority. If no such message is waiting in the queue, the ioctl will fail, and errno will be set to EAGAIN. dropped_msgs Whenever a message with KDBUS_MSG_SIGNAL is sent but cannot be queued on a peer (e.g., as it contains FDs but the peer does not support FDs, or there is no space left in the peer's pool) the 'dropped_msgs' counter of the peer is incremented. On the next RECV ioctl, the 'dropped_msgs' field is copied into the ioctl struct and cleared on the peer. If it was non-zero, the KDBUS_RECV_RETURN_DROPPED_MSGS flag will be set in return_flags. Note that this will only happen if the ioctl succeeded or failed with EAGAIN. In other error cases, the 'dropped_msgs' field of the peer is left untouched. msg Embedded struct containing information on the received message when this command succeeded (see below). items Items to specify further details for the receive command. Currently unused, and all items will be rejected with errno set to EINVAL. Both struct kdbus_cmd_recv and struct kdbus_cmd_send embed struct kdbus_msg_info. For the KDBUS_CMD_SEND ioctl, it is used to catch synchronous replies, if one was requested, and is unused otherwise. struct kdbus_msg_info { __u64 offset; __u64 msg_size; __u64 return_flags; }; The fields in this struct are described below. offset Upon return of the ioctl, this field contains the offset in the receiver's memory pool. The memory must be freed with KDBUS_CMD_FREE. See kdbus.pool 7 for further details. msg_size Upon successful return of the ioctl, this field contains the size of the allocated slice at offset offset. It is the combination of the size of the stored struct kdbus_msg object plus all appended VECs. You can use it in combination with offset to map a single message, instead of mapping the entire pool. See kdbus.pool 7 for further details. return_flags Kernel-provided return flags. Currently, the following flags are defined. KDBUS_RECV_RETURN_INCOMPLETE_FDS The message contained memfds or file descriptors, and the kernel failed to install one or more of them at receive time. Most probably that happened because the maximum number of file descriptors for the receiver's task were exceeded. In such cases, the message is still delivered, so this is not a fatal condition. File descriptors numbers inside the KDBUS_ITEM_FDS item or memfd files referenced by KDBUS_ITEM_PAYLOAD_MEMFD items which could not be installed will be set to -1. Unless KDBUS_RECV_DROP was passed, the offset field contains the location of the new message inside the receiver's pool after the KDBUS_CMD_RECV ioctl was employed. 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 when the KDBUS_CMD_RECV ioctl is called. memfds may always be part of the message payload. The receiving task is obliged to close all file descriptors appropriately once no longer needed. If KDBUS_RECV_PEEK is set, no file descriptors are installed. This allows for peeking at a message, looking at its metadata only and dropping it via KDBUS_RECV_DROP, without installing any of the file descriptors into the receiving process. The caller is obliged to call the KDBUS_CMD_FREE ioctl with the returned offset when the memory is no longer needed. A kernel notification is a regular kdbus message with the following details. kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL Has exactly one of the items attached that are described below. Always has a timestamp item (KDBUS_ITEM_TIMESTAMP) attached. The kernel will notify its users of the following events. When connection A is terminated while connection B is waiting for a reply from it, connection B is notified with a message with an item of type KDBUS_ITEM_REPLY_DEAD. When connection A does not receive a reply from connection B within the specified timeout window, connection A will receive a message with an item of type KDBUS_ITEM_REPLY_TIMEOUT. When an ordinary connection (not a monitor) is created on or removed from a bus, messages with an item of type KDBUS_ITEM_ID_ADD or KDBUS_ITEM_ID_REMOVE, respectively, are delivered to all bus members that match these messages through their match database. Eavesdroppers (monitor connections) do not cause such notifications to be sent. They are invisible on the bus. When a connection gains or loses ownership of a name, messages with an item of type KDBUS_ITEM_NAME_ADD, KDBUS_ITEM_NAME_REMOVE or KDBUS_ITEM_NAME_CHANGE are delivered to all bus members that match these messages through their match database. On success, all mentioned ioctl commands return 0; on error, -1 is returned, and errno is set to indicate the error. If the issued ioctl is illegal for the file descriptor used, errno will be set to ENOTTY. EOPNOTSUPP The connection is not an ordinary connection, or the passed file descriptors in KDBUS_ITEM_FDS item are either kdbus handles or unix domain sockets. Both are currently unsupported. EINVAL The submitted payload type is KDBUS_PAYLOAD_KERNEL, KDBUS_MSG_EXPECT_REPLY was set without timeout or cookie values, KDBUS_SEND_SYNC_REPLY was set without KDBUS_MSG_EXPECT_REPLY, an invalid item was supplied, src_id was non-zero and was different from the current connection's ID, a supplied memfd had a size of 0, or a string was not properly null-terminated. ENOTUNIQ The supplied destination is KDBUS_DST_ID_BROADCAST and either file descriptors were passed, or KDBUS_MSG_EXPECT_REPLY was set, or a timeout was given. E2BIG Too many items. EMSGSIZE The size of the message header and items or the payload vector is excessive. EEXIST Multiple KDBUS_ITEM_FDS, KDBUS_ITEM_BLOOM_FILTER or KDBUS_ITEM_DST_NAME items were supplied. EBADF The supplied KDBUS_ITEM_FDS or KDBUS_ITEM_PAYLOAD_MEMFD items contained an illegal file descriptor. EMEDIUMTYPE The supplied memfd is not a sealed kdbus memfd. EMFILE Too many file descriptors inside a KDBUS_ITEM_FDS. EBADMSG An item had illegal size, both a dst_id and a KDBUS_ITEM_DST_NAME was given, or both a name and a bloom filter was given. ETXTBSY The supplied kdbus memfd file cannot be sealed or the seal was removed, because it is shared with other processes or still mapped with mmap 2 . ECOMM A peer does not accept the file descriptors addressed to it. EFAULT The supplied bloom filter size was not 64-bit aligned, or supplied memory could not be accessed by the kernel. EDOM The supplied bloom filter size did not match the bloom filter size of the bus. EDESTADDRREQ dst_id was set to KDBUS_DST_ID_NAME, but no KDBUS_ITEM_DST_NAME was attached. ESRCH The name to look up was not found in the name registry. EADDRNOTAVAIL KDBUS_MSG_NO_AUTO_START was given but the destination connection is an activator. ENXIO The passed numeric destination connection ID couldn't be found, or is not connected. ECONNRESET The destination connection is no longer active. ETIMEDOUT Timeout while synchronously waiting for a reply. EINTR Interrupted system call while synchronously waiting for a reply. EPIPE When sending a message, a synchronous reply from the receiving connection was expected but the connection died before answering. ENOBUFS Too many pending messages on the receiver side. EREMCHG Both a well-known name and a unique name (ID) was given, but the name is not currently owned by that connection. EXFULL The memory pool of the receiver is full. EREMOTEIO While synchronously waiting for a reply, the remote peer failed with an I/O error. EOPNOTSUPP The connection is not an ordinary connection, or the passed file descriptors are either kdbus handles or unix domain sockets. Both are currently unsupported. EINVAL Invalid flags or offset. EAGAIN No message found in the queue. kdbus 7 kdbus.bus 7 kdbus.connection 7 kdbus.endpoint 7 kdbus.fs 7 kdbus.item 7 kdbus.name 7 kdbus.pool 7 clock_gettime 2 ioctl 2 poll 2 select 2 epoll 7 eventfd 2 memfd_create 2