kdbus.bus kdbus.bus 7 kdbus.bus kdbus bus A bus is a resource that is shared between connections in order to transmit messages (see kdbus.message 7 ). 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 mount instance it was created on. It has a custom name that is unique across all buses of a domain. In kdbus.fs 7 a bus is presented as a 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 effective UID of the creator and a dash. This is required to avoid namespace clashes between different users. When creating a bus, the 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 bus owner. 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 2 . 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 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). For more details on UUIDs, see the Wikipedia article on UUIDs. To create a new bus, the KDBUS_CMD_BUS_MAKE command is used. It takes a struct kdbus_cmd argument. struct kdbus_cmd { __u64 size; __u64 flags; __u64 return_flags; struct kdbus_item items[0]; }; The fields in this struct are described below. size The overall size of the struct, including its items. flags The flags for creation. KDBUS_MAKE_ACCESS_GROUP Make the bus file group-accessible. KDBUS_MAKE_ACCESS_WORLD Make the bus file world-accessible. 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. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. items The following items (see kdbus.item 7 ) are expected for KDBUS_CMD_BUS_MAKE. KDBUS_ITEM_MAKE_NAME Contains a null-terminated string that identifies the bus. The name must be unique across the kdbus domain and must start with the effective UID of the caller, followed by a '-' (dash). This item is mandatory. KDBUS_ITEM_BLOOM_PARAMETER Bus-wide bloom parameters passed in a struct kdbus_bloom_parameter. These settings are copied back to new connections verbatim. This item is mandatory. See kdbus.item 7 for a more detailed description of this item. KDBUS_ITEM_ATTACH_FLAGS_RECV An optional item that contains a set of required attach flags 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; in this case connections are free to set their own attach flags. KDBUS_ITEM_ATTACH_FLAGS_SEND An optional item that contains a set of attach flags that are returned to connections when they query the bus creator metadata. If not set, no metadata is returned. KDBUS_ITEM_NEGOTIATE With this item, programs can probe the kernel for known item types. See kdbus.item 7 for more details. Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. 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. EBADMSG A mandatory item is missing. EINVAL The flags supplied in the struct kdbus_cmd are invalid or the supplied name does not start with the current UID and a '-' (dash). EEXIST A bus of that name already exists. ESHUTDOWN The kdbus mount instance for the bus was already shut down. EMFILE The maximum number of buses for the current user is exhausted. kdbus 7 kdbus.connection 7 kdbus.endpoint 7 kdbus.fs 7 kdbus.item 7 kdbus.message 7 kdbus.name 7 kdbus.pool 7