kdbus.endpoint kdbus.endpoint 7 kdbus.endpoint kdbus endpoint Endpoints are entry points to a bus (see kdbus.bus 7 ). By default, each bus has a default endpoint called 'bus'. The bus owner has the ability to create custom endpoints with specific names, permissions, and policy databases (see below). An endpoint is presented as file underneath the directory of the parent bus. To create a custom endpoint, open the default endpoint (bus) and use the KDBUS_CMD_ENDPOINT_MAKE ioctl with struct kdbus_cmd. Custom endpoints always have a policy database that, by default, forbids any operation. You have to explicitly install policy entries to allow any operation on this endpoint. Once KDBUS_CMD_ENDPOINT_MAKE succeeded, the new endpoint will appear in the filesystem ( kdbus.bus 7 ), and the used file descriptor will manage the newly created endpoint resource. It cannot be used to manage further resources and must be kept open as long as the endpoint is needed. The endpoint will be terminated as soon as the file descriptor is closed. 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-my-endpoint 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 bus. To create connections to a bus, use KDBUS_CMD_HELLO on a file descriptor returned by open() on an endpoint node. See kdbus.connection 7 for further details. To create a new endpoint, the KDBUS_CMD_ENDPOINT_MAKE command is used. Along with the endpoint's name, which will be used to expose the endpoint in the kdbus.fs 7 , the command also optionally takes items to set up the endpoint's kdbus.policy 7 . KDBUS_CMD_ENDPOINT_MAKE 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 endpoint file group-accessible. KDBUS_MAKE_ACCESS_WORLD Make the endpoint 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 are expected for KDBUS_CMD_ENDPOINT_MAKE. KDBUS_ITEM_MAKE_NAME Contains a string to identify the endpoint name. KDBUS_ITEM_NAME KDBUS_ITEM_POLICY_ACCESS These items are used to set the policy attached to the endpoint. For more details on bus and endpoint policies, see kdbus.policy 7 . Unrecognized items are rejected, and the ioctl will fail with errno set to EINVAL. To update an existing endpoint, the KDBUS_CMD_ENDPOINT_UPDATE command is used on the file descriptor that was used to create the endpoint, using KDBUS_CMD_ENDPOINT_MAKE. The only relevant detail of the endpoint that can be updated is the policy. When the command is employed, the policy of the endpoint is replaced atomically with the new set of rules. The command 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 Unused for this command. KDBUS_FLAG_NEGOTIATE is accepted to probe for valid flags. If set, the ioctl will return 0, and the flags field is set to 0. return_flags Flags returned by the kernel. Currently unused and always set to 0 by the kernel. items The following items are expected for KDBUS_CMD_ENDPOINT_UPDATE. KDBUS_ITEM_NAME KDBUS_ITEM_POLICY_ACCESS These items are used to set the policy attached to the endpoint. For more details on bus and endpoint policies, see kdbus.policy 7 . Existing policy is atomically replaced with the new rules provided. 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. EINVAL The flags supplied in the struct kdbus_cmd are invalid. EINVAL Illegal combination of KDBUS_ITEM_NAME and KDBUS_ITEM_POLICY_ACCESS was provided. EEXIST An endpoint of that name already exists. EPERM The calling user is not privileged. See kdbus 7 for information about privileged users. EINVAL The flags supplied in struct kdbus_cmd are invalid. EINVAL Illegal combination of KDBUS_ITEM_NAME and KDBUS_ITEM_POLICY_ACCESS was provided. kdbus 7 kdbus.bus 7 kdbus.endpoint 7 kdbus.fs 7 kdbus.item 7 kdbus.message 7 kdbus.name 7 kdbus.pool 7