From 57f0f512b273f60d52568b8c6b77e17f5636edc0 Mon Sep 17 00:00:00 2001 From: André Fabian Silva Delgado Date: Wed, 5 Aug 2015 17:04:01 -0300 Subject: Initial import --- Documentation/kdbus/kdbus.bus.xml | 344 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 Documentation/kdbus/kdbus.bus.xml (limited to 'Documentation/kdbus/kdbus.bus.xml') diff --git a/Documentation/kdbus/kdbus.bus.xml b/Documentation/kdbus/kdbus.bus.xml new file mode 100644 index 000000000..83f1198bc --- /dev/null +++ b/Documentation/kdbus/kdbus.bus.xml @@ -0,0 +1,344 @@ + + + + + + + kdbus.bus + kdbus.bus + + + + kdbus.bus + 7 + + + + kdbus.bus + kdbus bus + + + + Description + + + 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. + + + + + + Creating buses + + 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_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. + + + + + Return value + + 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. + + + + + <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following + errors + + + + + 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. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.name + 7 + + + + + kdbus.pool + 7 + + + + + -- cgit v1.2.3-54-g00ecf