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.endpoint.xml | 429 +++++++++++++++++++++++++++++++++ 1 file changed, 429 insertions(+) create mode 100644 Documentation/kdbus/kdbus.endpoint.xml (limited to 'Documentation/kdbus/kdbus.endpoint.xml') diff --git a/Documentation/kdbus/kdbus.endpoint.xml b/Documentation/kdbus/kdbus.endpoint.xml new file mode 100644 index 000000000..6632485f3 --- /dev/null +++ b/Documentation/kdbus/kdbus.endpoint.xml @@ -0,0 +1,429 @@ + + + + + + + kdbus.endpoint + kdbus.endpoint + + + + kdbus.endpoint + 7 + + + + kdbus.endpoint + kdbus endpoint + + + + Description + + + 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. + + + + + Creating custom endpoints + + 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. + + + + + + + + Updating endpoints + + 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. + + + + + + + + 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_ENDPOINT_MAKE</constant> may fail with the + following errors + + + + + 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. + + + + + + + + <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the + following errors + + + + + EINVAL + + The flags supplied in struct kdbus_cmd + are invalid. + + + + + EINVAL + + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. + + + + + + + + See Also + + + + kdbus + 7 + + + + + kdbus.bus + 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