From: Daniel Mack Date: Fri, 23 Jan 2015 19:25:47 +0000 (+0100) Subject: doc: convert documentation to docbook-xml X-Git-Tag: upstream/0.20150129.081441utc~23 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1262d9e580cdab18501bd4020505f718ccc51f06;p=platform%2Fcore%2Fsystem%2Fkdbus-bus.git doc: convert documentation to docbook-xml This is work in progress and not finished yet. Signed-off-by: Daniel Mack --- diff --git a/.gitignore b/.gitignore index 4b97bee..c2ccf21 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ Module.symvers tags tools/kdbus-monitor test/kdbus-test +doc/html +doc/man diff --git a/Makefile b/Makefile index 0e7dec4..419acd9 100644 --- a/Makefile +++ b/Makefile @@ -45,7 +45,12 @@ clean: check: test/kdbus-test -doc: +mandoc: + $(MAKE) -C doc mandoc + +doc: mandoc + +kerneldoc_check: $(KERNELDIR)/scripts/kernel-doc *.c kdbus.h >/dev/null | grep "^Warning" install: module diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..7b421f7 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,3 @@ +*.7 +manpage.* +*.proc diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..3f14c72 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,18 @@ +docs= \ + kdbus.xml \ + kdbus.bus.xml \ + kdbus.connection.xml \ + kdbus.endpoint.xml \ + kdbus.fs.xml \ + kdbus.item.xml \ + kdbus.message.xml \ + kdbus.names.xml \ + kdbus.pool.xml + +manpages=$(docs:.xml=.7) + +%.7: %.xml + xmlto man -m stylesheet.xsl -o . $< + +mandoc: $(manpages) + diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml new file mode 100644 index 0000000..d7e14e3 --- /dev/null +++ b/doc/kdbus.bus.xml @@ -0,0 +1,249 @@ + + + + + + + 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.message7). + 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.fs7), + 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, that 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 + parent domain. + + + 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(). + + + 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 by userspace 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 entry on UUIDs. + + + + + + Creating buses and endpoints + + To create a new bus, the KDBUS_CMD_BUS_MAKE + command is used. It takes a struct kdbus_cmd_make argument. + + +struct kdbus_cmd_make { + __u64 size; + __u64 flags; + __u64 kernel_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 or endpoint file group-accessible + + + + + KDBUS_MAKE_ACCESS_WORLD + + Make the bus or endpoint file world-accessible + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + The following items are expected for + KDBUS_CMD_BUS_MAKE. + + + + KDBUS_ITEM_MAKE_NAME + + Contains a string to identify the bus name. + + + + + KDBUS_ITEM_BLOOM_PARAMETER + + Bus-wide bloom parameters passed in a + struct kdbus_bloom_parameter. These + settings are copied back to new connections verbatim. + + + + + + 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. + + + + + + + + + + Unrecognized items are rejected, and the ioctl will fail with -EINVAL. + + + + + Return value + + On success, all mentioned ioctl commands return 0. + + + + KDBUS_CMD_BUS_MAKE may return the following errors. + + + + + -EINVAL + + The flags supplied in the struct kdbus_cmd_make + are invalid or the supplied name does not start with the current + UID and a '-'. + + + + + -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 + + kdbus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml new file mode 100644 index 0000000..133022e --- /dev/null +++ b/doc/kdbus.connection.xml @@ -0,0 +1,970 @@ + + + + + + + kdbus.connection + kdbus.connection + + + + kdbus.connection + 7 + + + + kdbus.connection + kdbus connection + + + + Description + + + Connections are identified by their connection ID, + internally implemented as a uint64_t counter. + The IDs of every newly created bus start at 1, and every new + connection will increment the counter by 1. The IDs are not reused. + + + In higher level tools, the user visible representation of a connection is + defined by the D-Bus protocol specification as + ":1.<ID>". + + + Messages with a specific uint64_t destination ID are + directly delivered to the connection with the corresponding ID. Messages + with the special destination ID KDBUS_DST_ID_BROADCAST + are broadcast messages and are potentially delivered to all currently + active connections on the bus. However, in order to receive any broadcast + messages, clients must subscribe to the specific messages in which they are + interested in. + + + Messages synthesized and sent directly by the kernel will carry the special + source ID KDBUS_SRC_ID_KERNEL (0). + + + In addition to the unique uint64_t connection ID, + established connections can request the ownership of + well-known names, under which they can be found and + addressed by other bus clients. A well-known name is associated with one + and only one connection at a time. See + kdbus.names7 + on name acquisition, the name registry, and the validity of names. + + + Messages can specify the special destination ID 0 and carry a well-known name + in the message data. Such a message is delivered to the destination connection + which owns that well-known name. + + + | src: 22 | | | + | | | | dst: 25 | | | + | | | | | | | + | | | | | | | + | | | +---------------------------+ | | + | | | | | + | | | <--------------------------------------+ | | + | +---------------+ | | | + | | | | + | +---------------+ +---------------------------+ | | | + | | Connection | | Message | -----+ | | + | | :1.25 | --> | src: 25 | | | + | | | | dst: 0xffffffffffffffff | -------------+ | | + | | | | (KDBUS_DST_ID_BROADCAST) | | | | + | | | | | ---------+ | | | + | | | +---------------------------+ | | | | + | | | | | | | + | | | <--------------------------------------------------+ | + | +---------------+ | | | + | | | | + | +---------------+ +---------------------------+ | | | + | | Connection | | Message | --+ | | | + | | :1.55 | --> | src: 55 | | | | | + | | | | dst: 0 / org.foo.bar | | | | | + | | | | | | | | | + | | | | | | | | | + | | | +---------------------------+ | | | | + | | | | | | | + | | | <------------------------------------------+ | | + | +---------------+ | | | + | | | | + | +---------------+ | | | + | | Connection | | | | + | | :1.81 | | | | + | | org.foo.bar | | | | + | | | | | | + | | | | | | + | | | <-----------------------------------+ | | + | | | | | + | | | <----------------------------------------------+ | + | +---------------+ | + +-------------------------------------------------------------------------+ + ]]> + + + + Creating connections + + A connection to a bus is created by opening an endpoint file of a bus and + becoming an active client with the KDBUS_CMD_HELLO + ioctl. Every connected client connection has a unique identifier on the + bus and can address messages to every other connection on the same bus + by using the peer's connection ID as the destination. + + + The KDBUS_CMD_HELLO ioctl takes the following struct as argument. + + + +struct kdbus_cmd_hello { + __u64 size; + __u64 flags; + __u64 kernel_flags; + __u64 return_flags; + __u64 attach_flags_send; + __u64 attach_flags_recv; + __u64 bus_flags; + __u64 id; + __u64 pool_size; + __u64 offset; + __u8 id128[16]; + 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 apply to this connection + + + KDBUS_HELLO_ACCEPT_FD + + + When this flag is set, the connection can be sent file + descriptors as message payload. If it's not set, an attempt + to send file descriptors results in -ECOMM + on the sender's side. + + + + + + KDBUS_HELLO_ACTIVATOR + + + Make this connection an activator (see below). With this bit + set, an item of type KDBUS_ITEM_NAME has + to be attached. This item describes the well-known name this + connection should be an activator for. + + + + + + KDBUS_HELLO_POLICY_HOLDER + + + Make this connection a policy holder (see below). With this + bit set, an item of type KDBUS_ITEM_NAME + has to be attached. This item describes the well-known name + this connection should hold a policy for. + + + + + + KDBUS_HELLO_MONITOR + + + Make this connection an monitor (eavesdropping) connection. + See the section below more information. + + + This flag can only be set by privileged bus connections. See + below. + + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + attach_flags_send + + Set the bits for metadata this connection permits to be sent to the + receiving peer. Only metadata items that are both allowed to be sent + by the sender and that are requested by the receiver will effectively + be attached to the message. Note, however, that the bus may + optionally require some of those bits to be set. If the match fails, + -ECONNREFUSED will be returned. In either case, + this field will be set to the mask of metadata items that are + enforced by the bus. The KDBUS_FLAGS_KERNEL bit + will as well be set. + + + + + attach_flags_recv + + Request the attachment of metadata for each message received by this + connection. See XXX TODO XXX for more details. + + + + + bus_flags + + Upon successful completion of the ioctl, this member will contain the + flags of the bus it connected to. + + + + + id + + Upon successful completion of the command, this member will contain + the numerical ID of the new connection. + + + + + pool_size + + The size of the communication pool, in bytes. The pool can be + accessed by calling + mmap2 + on the file descriptor that was used to issue the + KDBUS_CMD_HELLO ioctl. + + + See + kdbus.pool7 + for further information. + + + + + offset + + The kernel will return the offset in the pool where returned details + will be stored. See below. + + + + + id128 + + Upon successful completion of the ioctl, this member will contain the + 128-bit UUID of the connected bus. + + + + + items + + + Variable list of items containing optional additional information. + The following items are currently expected/valid: + + + + KDBUS_ITEM_CONN_DESCRIPTION + + + Contains a string that describes this connection, so it can + be identified later. + + + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + For activators and policy holders only, combinations of + these two items describe policy access entries. See XXX TODO XXX. + + + + + + KDBUS_ITEM_CREDS + KDBUS_ITEM_PIDS + KDBUS_ITEM_SECLABEL + + + Privileged bus users may submit these types in order to + create connections with faked credentials. This information + will be returned when peer information is queried by + KDBUS_CMD_CONN_INFO. See below for more + information on retrieving information on connections. + + + + + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + At the offset returned in the offset field of + struct kdbus_cmd_hello, the kernel will store items + of the following types: + + + + + KDBUS_ITEM_BLOOM_PARAMETER + + + Bloom filter parameter as defined by the bus creator. + + + + + + + The offset in the pool has to be freed with the + KDBUS_CMD_FREE ioctl. See + kdbus.pool7 + for further information. + + + + + Privileged connections + + A connection is considered privileged if the user + it was created by is the same that created the bus, or if the creating + task had CAP_IPC_OWNER set when it called + KDBUS_CMD_HELLO. + + + Privileged connections have permission to employ certain restricted + functions and commands, which are explained below and in other kdbus + manpages. + + + + + Activator and policy holder connection + + An activator connection is a placeholder for a + well-known name. Messages sent to such a connection + can be used by userspace to start an implementer connection, which will + then get all the messages from the activator copied over. An activator + connection cannot be used to send any message. + + + A policy holder connection only installs a policy + for one or more names. These policy entries are kept active as long as + the connection is alive, and are removed once it terminates. Such a + policy connection type can be used to deploy restrictions for names that + are not yet active on the bus. A policy holder connection cannot be used + to send any message. + + + The creation of activator, policy holder or monitor (eavesdropping) + connections is an operation restricted to privileged users on the bus. + See the section below on privileged connections. + + + + + Retrieving information on a connection + + The KDBUS_CMD_CONN_INFO ioctl can be used to retrieve + credentials and properties of the initial creator of a connection. This + ioctl uses the following struct. + + + +struct kdbus_cmd_info { + __u64 size; + __u64 flags; + __u64 kernel_flags; + __u64 return_flags; + __u64 id; + __u64 offset; + __u64 info_size; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Specifies which metadata items should be attached to the answer. + See + kdbus.message7 + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + id + + The numerical ID of the connection for which information is to be + retrieved. If set to a non-zero value, the + KDBUS_ITEM_OWNED_NAME item is ignored. + + + + + offset + + When the ioctl returns, this field will contain the offset of the + connection information inside the caller's pool. See + kdbus.pool7 + for futher information. + + + + + + + The kernel will return the size of the returned information, so applications + can optionally + mmap2 + specific parts of the pool. See + kdbus.pool7 + for futher information. + + + + + items + + + The following items are expected for + KDBUS_CMD_CONN_INFO. + + + + KDBUS_ITEM_OWNED_NAME + + + Contains the well-known name of the connection to look up as. + This item is mandatory if the id field is + set to 0. + + + + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + When the ioctl returns, the following struct will be stored in the + caller's pool at offset. The fields in this struct + are described below. + + + +struct kdbus_info { + __u64 size; + __u64 id; + __u64 flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + id + + The connection's unique ID. + + + + + flags + + The connection's flags as specified when it was created. + + + + + items + + + Depending on the flags field in + struct kdbus_cmd_info, items of types + KDBUS_ITEM_OWNED_NAME and + KDBUS_ITEM_CONN_DESCRIPTION may follow here. + + + + + + + Once the caller is finished with parsing the return buffer, it needs to + employ the KDBUS_CMD_FREE command for the offset, in + order to free the buffer part. See + kdbus.pool7 + for futher information. + + + + + Getting information about a connection's bus creator + + The KDBUS_CMD_BUS_CREATOR_INFO ioctl takes the same + struct as KDBUS_CMD_CONN_INFO, but is used to retrieve + information about the creator of the bus the connection is attached to. + The metadata returned by this call is collected during the creation of + the bus and is never altered afterwards, so it provides pristine + information on the task that created the bus, at the moment when it + did so. + + + In response to this call, a slice in the connection's pool is allocated and + filled with an object of type struct kdbus_info, + pointed to by the ioctl's offset field. + + + +struct kdbus_info { + __u64 size; + __u64 id; + __u64 flags; + __u64 kernel_flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + id + + The bus ID. + + + + + flags + + The bus flags as specified when it was created. + + + + + items + + + Metadata information is stored in items here. The item list + contains a KDBUS_ITEM_MAKE_NAME item that + indicates the bus name of the calling connection. + + + + + + + Once the caller is finished with parsing the return buffer, it needs to + employ the KDBUS_CMD_FREE command for the offset, in + order to free the buffer part. See + kdbus.pool7 + for futher information. + + + + + Updating connection details + + Some of a connection's details can be updated with the + KDBUS_CMD_CONN_UPDATE ioctl, using the file + descriptor that was used to create the connection. The update command + uses the following struct. + + + +struct kdbus_cmd_update { + __u64 size; + __u64 flags; + __u64 kernel_flags; + struct kdbus_item items[0]; +}; + + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Currently, no flags are supported. Reserved for future use. + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + Items to describe the connection details to be updated. The + following item types are supported. + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + + + Supply a new set of items that this connection permits to be + sent along with messages. + + + + + + KDBUS_ITEM_ATTACH_FLAGS_RECV + + + Supply a new set of items to be attached to each message. + + + + + + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS + + + Policy holder connections may supply a new set of policy + information with these items. For other connection types, + -EOPNOTSUPP is returned. + + + + + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + + Monitor connections ('eavesdropper') + + Eavesdropping connections are created by setting the + KDBUS_HELLO_MONITOR flag in + struct kdbus_hello.flags. + Such connections have all properties of any other, regular connection, + except for the following details: + + + + + They will get every message sent over the bus, both unicasts and + broadcasts. + + + + Installing matches for signal messages is neither necessary + nor allowed. + + + + They cannot send messages or be directly addressed as receiver + + + + Their creation and destruction will not cause + KDBUS_ITEM_ID_{ADD,REMOVE} notifications to be + generated, so other connections cannot detect the presence of an + eavesdropper. + + + + + + Termination of connections + + A connection can be terminated by simply calling + close2 + on its file descriptor. All pending incoming messages will be discarded, + and the memory allocated by the pool will be freed. + + + + An alternative way of closing down a connection is via the + KDBUS_CMD_BYEBYE ioctl. This ioctl will succeed only + if the message queue of the connection is empty at the time of closing; + otherwise, -EBUSY is returned. When this ioctl returns + successfully, the connection has been terminated and won't accept any new + messages from remote peers. This way, a connection can be terminated + race-free, without losing any messages. + + + + + Return value + + On success, all metioned ioctl commands return 0. + + + + KDBUS_CMD_HELLO may return the following errors. + + + + + -EFAULT + + The supplied pool size was 0 or not a multiple of the page size. + + + + + -EINVAL + + The flags supplied in struct kdbus_cmd_make are + invalid, or an illegal combination of + KDBUS_HELLO_MONITOR, + KDBUS_HELLO_ACTIVATOR and + KDBUS_HELLO_POLICY_HOLDER was passed in the flags, + or an invalid set of items was supplied. + + + + + -ECONNREFUSED + + The attach_flags_send field did not satisfy the requirements of + the bus. + + + + + -EPERM + + A KDBUS_ITEM_CREDS items was supplied, but the + current user is not privileged. + + + + + -ESHUTDOWN + + The bus you were trying to connect to has already been shut down. + + + + + -EMFILE + + The maximum number of connections on the bus has been reached. + + + + + -EOPNOTSUPP + + The endpoint does not support the connection flags supplied in + struct kdbus_cmd_hello. + + + + + + KDBUS_CMD_BYEBYE may return the following errors. + + + + + -EALREADY + + The connection has already been shut down. + + + + + -EBUSY + + There are still messages queued up in the connection's pool. + + + + + + KDBUS_CMD_CONN_INFO may return the following errors. + + + + + -EINVAL + + Invalid flags, or neither an ID nor a name was provided, or the + name is invalid. + + + + + -ESRCH + + Connection lookup by name failed. + + + + + -ENXIO + + No connection with the provided connection ID found. + + + + + + KDBUS_CMD_CONN_UPDATE may return the following errors. + + + + + -EINVAL + + Illegal flags or items. + + + + + -EINVAL + + Wildcards submitted in policy entries, or illegal sequence + of policy items. + + + + + -EOPNOTSUPP + + Operation not supported by connection. + + + + + -E2BIG + + Too many policy items attached. + + + + + + + + See Also + + kdbus7 + + kdbus.bus7 + kdbus.endpoint7 + kdbus.message7 + kdbus.pool7 + kdbus.items7 + + + diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml new file mode 100644 index 0000000..f48bccb --- /dev/null +++ b/doc/kdbus.endpoint.xml @@ -0,0 +1,210 @@ + + + + + + + kdbus.endpoint + kdbus.endpoint + + + + kdbus.endpoint + 7 + + + + kdbus.endpoint + kdbus endpoint + + + + Description + + + Endpoints are entry points to a bus (see + kdbus.bus7). + 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_make". 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.bus7), + 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-foobar" 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 parent domain. + + + To create connections to a bus, use KDBUS_CMD_HELLO on a file descriptor returned by + open2 + on an endpoint node. + See kdbus.connection7 + for further details. + + + + + Creating custom endpoints + + To create a new endpoint, the KDBUS_CMD_ENDPOINT_MAKE + command is used. It takes a struct kdbus_cmd_make argument. + + +struct kdbus_cmd_make { + __u64 size; + __u64 flags; + __u64 kernel_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 + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero 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. + + + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + + Updating endpoints + + TODO!! Document KDBUS_CMD_ENPOINT_UPDATE + + + + + Return value + + On success, all mentioned ioctl commands return 0. + + + + KDBUS_CMD_ENDPOINT_MAKE may return the following errors. + + + + + -EINVAL + + The flags supplied in the struct kdbus_cmd_make + are invalid. + + + + + -EEXIST + + An endpoint of that name already exists. + + + + + -EPERM + + The calling user is not privileged. See + kdbus7 + for information about privileged users. + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + diff --git a/doc/kdbus.fs.xml b/doc/kdbus.fs.xml new file mode 100644 index 0000000..75d00f0 --- /dev/null +++ b/doc/kdbus.fs.xml @@ -0,0 +1,74 @@ + + + + + + + kdbus.fs + kdbus.fs + + + + kdbus.fs + 7 + + + + kdbus.fs + kdbus file system + + + + File-system Layout + + The kdbusfs + pseudo file-system provides access to internal kdbus entities, + including buses and endpoints. Each time you mount it, a new + instance (called domain) will be created + which is independent of the other domains. + + Following, you can see an example layout of the + kdbusfs file-system: + + + /sys/fs/kdbus/ ; mount-point + |-- 0-system ; bus directory + | |-- bus ; default endpoint + | `-- 1017-custom ; custom endpoint + |-- 1000-user ; bus directory + | |-- bus ; default endpoint + | |-- 1000-service-A ; custom endpoint + | `-- 1000-service-B ; custom endpoint + `-- control ; control file + + + + + Mounting instances + In order to get a new and separate kdbus environment, new instance + of kdbusfs can be mounted like this: + + # mount -t kdbusfs kdbusfs /tmp/new_kdbus/ + + + + Busses created in this new instance will be entirely separated and + not influence any other kdbus instances on the system. + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + mount8 + + + diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml new file mode 100644 index 0000000..46722fbe --- /dev/null +++ b/doc/kdbus.item.xml @@ -0,0 +1,351 @@ + + + + + + + kdbus.item + kdbus item + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + Developer + Daniel + Mack + kdbus@zonque.org + + + + + + kdbus.item + 7 + + + + kdbus.item + Kernel item structure + + + + Description + + + To flexibly augment transport structures, data blobs of type + struct kdbus_item + can be attached to the structs passed into the ioctls. Some ioctls make items + of certain types mandatory, others are optional. Items that are unsupported + by ioctls they are sent to will cause the ioctl to fail + -EINVAL. + Items are also used for information stored in a connection's + pool, such as received messages, name lists or + requested connection or bus owner information. Depending on the type of + an item, its total size is either fixed or variable. + The kernel expects all items to be aligned to 8-byte boundaries. Unaligned + items or items that are unsupported by the ioctl are rejected. + + + Whenever items are used as part of the kdbus kernel API, they are embedded in + structs that are embedded inside structs that themselves include a size field + containing the overall size of the structure. This allows multiple items to + be chained up. + + + + Iterating items + A simple iterator in userspace would iterate over the items until the items + have reached the embedding structure's overall size. An example implementation + is shown below. + + + size)) + +#define KDBUS_ITEM_FOREACH(item, head, first) \ + for (item = (head)->first; \ + ((uint8_t *)(item) < (uint8_t *)(head) + (head)->size) && \ + ((uint8_t *)(item) >= (uint8_u *)(head)); \ + item = KDBUS_ITEM_NEXT(item)) + ]]> + + + + Item layout + A struct kdbus_item consists of a + size field, describing its overall size, + and a type field, both 64 bit wide. They are followed by + a union to store information that is specific to the item's type. + A shortened version is shown below. + + + +struct kdbus_item { + __u64 size; + __u64 type; + union { + /* item type specific payload - see below */ + }; +}; + + + struct kdbus_item should never be + used to allocate an item instance, as its size may grow in future + releases of the API. Instead, it should be manually assembled by storing + the size, type + and payload to a struct of its own. + + + + + Item types + + Items exchanged between userspace and kernel + + + KDBUS_ITEM_PAYLOAD_VEC + + + + + + KDBUS_ITEM_PAYLOAD_OFF + TODO + + + + + KDBUS_ITEM_PAYLOAD_MEMFD + TODO + + + + + KDBUS_ITEM_FDS + TODO + + + + + KDBUS_ITEM_CANCEL_FD + TODO + + + + + KDBUS_ITEM_BLOOM_PARAMETER + TODO + + + + + KDBUS_ITEM_BLOOM_FILTER + TODO + + + + + KDBUS_ITEM_BLOOM_MASK + TODO + + + + + KDBUS_ITEM_DST_NAME + TODO + + + + + KDBUS_ITEM_MAKE_NAME + TODO + + + + + KDBUS_ITEM_ATTACH_FLAGS_SEND + TODO + + + + + KDBUS_ITEM_ATTACH_FLAGS_RECV + TODO + + + + + KDBUS_ITEM_ID + TODO + + + + + KDBUS_ITEM_NAME + TODO + + + + + Items attached by the kernel as metadata + + + + KDBUS_ITEM_TIMESTAMP + TODO + + + + + KDBUS_ITEM_CREDS + TODO + + + + + KDBUS_ITEM_PIDS + TODO + + + + + KDBUS_ITEM_AUXGROUPS + TODO + + + + + KDBUS_ITEM_OWNED_NAME + TODO + + + + + KDBUS_ITEM_TID_COMM + TODO + + + + + KDBUS_ITEM_PID_COMM + TODO + + + + + KDBUS_ITEM_EXE + TODO + + + + + KDBUS_ITEM_CMDLINE + TODO + + + + + KDBUS_ITEM_CGROUP + TODO + + + + + KDBUS_ITEM_CAPS + TODO + + + + + KDBUS_ITEM_SECLABEL + TODO + + + + + KDBUS_ITEM_AUDIT + TODO + + + + + KDBUS_ITEM_CONN_DESCRIPTION + TODO + + + + + Items used for policy entries, matches and notifications + + + + KDBUS_ITEM_NAME_ADD + TODO + + + + + KDBUS_ITEM_NAME_REMOVE + TODO + + + + + KDBUS_ITEM_NAME_CHANGE + TODO + + + + + KDBUS_ITEM_ID_ADD + TODO + + + + + KDBUS_ITEM_ID_REMOVE + TODO + + + + + KDBUS_ITEM_REPLY_TIMEOUT + TODO + + + + + KDBUS_ITEM_REPLY_DEAD + TODO + + + + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + + diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml new file mode 100644 index 0000000..9c529a4 --- /dev/null +++ b/doc/kdbus.message.xml @@ -0,0 +1,1030 @@ + + + + + + + kdbus.message + kdbus.message + + + + kdbus.message + 7 + + + + kdbus.message + kdbus message + + + + Description + + + 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 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 below). + + + + 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 kernel_flags; + __u64 kernel_msg_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_MSG_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 in + 'offset_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. + + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + msg_address + + In this field, userspace has 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() on this file descriptor, + and if it reports any incoming bytes, the blocking send operation will + be canceled, and the call will return -ECANCELED. Any type of file + descriptor that implements poll() can be used as payload to this item. + For asynchronous message sending, this item is accepted but ignored. + + + + + + All other items are rejected, and the ioctl will fail with -EINVAL. + + + + + + + The fields in this struct are described below. + The message referenced 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 its kdbus_msg.reply_cookie + 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, + -EADDRNOTAVAIL is returned from the ioctl. + + + + + + + + + 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 zero. + + + + + 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. + + + + + 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_gettime2. + + + + + 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 + "Passing of Payload Data". + + + + + + 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, + -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 userspace 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 TODO! + + + + + Message layout + + 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 ... | + +-------------------------------------------------------------------------+ + + + + + Passing of Payload Data + + + 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.pool7 + for more information. + + + + The following items are used to carry the actual data payload of a message. + + + + + KDBUS_MSG_PAYLOAD_VEC + + + Messages are directly copied by the sending process 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. + + + + + + KDBUS_MSG_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. + + + Apart from the sender filling-in the content into memfd files, the data will + be passed as zero-copy from one process to another, read-only, shared between + the peers. + + + + + + + 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 VEC and 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 + hunks than it was sent as. + + + + + Receiving messages + + + Messages are received by the client with the KDBUS_CMD_RECV ioctl. + The endpoint file of the bus supports poll/epoll/select + to wake up the receiving process when new messages are queued up to be received. + + + + With the KDBUS_CMD_RECV ioctl, a struct kdbus_cmd_recv is used. + + + +struct kdbus_cmd_recv { + __u64 size; + __u64 flags; + __u64 kernel_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). + + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + 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, -ENOMSG is returned. + + + + + dropped_msgs + + If the CMD_RECV ioctl fails with + -EOVERFLOW, this field is filled by + the kernel with the number of messages that couldn't be transmitted + to this receiving connection. In that case, the + offset member must not be accessed. + + + + + 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 + -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.pool7 + 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.pool7 + for further details. + + + + + return_flags + + + Kernel-provided return flags. Currently, the following flags are defined. + + + + KDBUS_RECV_RETURN_INCOMPLETE_FDS + + + The message contained file descriptors which couldn't be installed + into the receiver's task. Most probably that happened because the + maximum number of file descriptors for that task were exceeded. + The message is still delivered, so this is not a fatal condition. + File descriptors inside the KDBUS_ITEM_FDS + item that could not be installed will be set to -1. + + + + + + + + + + Unless KDBUS_RECV_DROP was passed after a successful+ + KDBUS_CMD_RECV ioctl, the offset + field contains the location of the new message inside the receiver's + pool. 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. + The receiving task is obliged to close all of them appropriately. If + KDBUS_RECV_PEEK is set, no file descriptors are + installed. This allows for peeking at a message and dropping it via + KDBUS_RECV_DROP, without installing the passed 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. + + + + + Notifications + + 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 aforementioned items attached + + + + Kernel notifications have an item of type 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. + + + + + + Return value + + On success, all metioned ioctl commands return 0. + + + + KDBUS_CMD_SEND may return the following errors. + + + + + -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 + + 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, + a file descriptor was passed, KDBUS_MSG_EXPECT_REPLY + was set, or a timeout was given for a broadcast message. + + + + + -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 + mmap2. + + + + + -ECOMM + + A peer does not accept the file descriptors addressed to it. + + + + + -EFAULT + + The supplied bloom filter size was not 64-bit aligned or memory + supplied by userspace 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. + + + + + + KDBUS_CMD_RECV may return the following errors. + + + + + -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 + + + + + -ENOMSG + + No message of the requested priority found. + + + + + -EOVERFLOW + + Some messages have been lost. + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.items7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + clock_gettime2 + ioctl2 + poll2 + select2 + epoll7 + + + diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml new file mode 100644 index 0000000..b259472 --- /dev/null +++ b/doc/kdbus.names.xml @@ -0,0 +1,582 @@ + + + + + + + kdbus.names + kdbus.names + + + + kdbus.names + 7 + + + + kdbus.names + kdbus names + + + + Description + + Each + kdbus.bus7 + instantiates a name registry to resolve well-known names into unique + connection IDs for message delivery. The registry will be queried when a + message is sent with kdbus_msg.dst_id set to + KDBUS_DST_ID_NAME, or when a registry dump is + requested. + + + + All of the below is subject to policy rules for SEE and OWN permissions. + See + kdbus.policy7 + for more information. + + + + + Name validity + + A name has to comply with the following rules to be considered valid. + + + + + The name has two or more elements separated by a period ('.') character + + + All elements must contain at least one character + + + Each element must only contain the ASCII characters "[A-Z][a-z][0-9]_" + and must not begin with a digit + + + The name must contain at least one '.' (period) character + (and thus at least two elements) + + + The name must not begin with a '.' (period) character + + + The name must not exceed KDBUS_NAME_MAX_LEN (255) + + + + + + Acquiring a name + + To acquire a name, a client uses the + KDBUS_CMD_NAME_ACQUIRE ioctl with the following data + structure. + + + +struct kdbus_cmd_name { + __u64 size; + __u64 flags; + __u64 kernel_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 + Flags to control details in the name acquisition. + + + KDBUS_NAME_REPLACE_EXISTING + + + Acquiring a name that is already present usually fails, + unless this flag is set in the call, and + KDBUS_NAME_ALLOW_REPLACEMENT (see below) + was set when the current owner of the name acquired it, or + if the current owner is an activator connection (see + kdbus.connection7). + + + + + + KDBUS_NAME_ALLOW_REPLACEMENT + + + Allow other connections to take over this name. When this + happens, the former owner of the connection will be notified + of the name loss. + + + + + + KDBUS_NAME_QUEUE + + + A name that is already acquired by a connection, and which + wasn't requested with the + KDBUS_NAME_ALLOW_REPLACEMENT flag set can + not be acquired again. However, a connection can put itself + in a queue of connections waiting for the name to be released. + Once that happens, the first connection in that queue becomes + the new owner and is notified accordingly. + + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + Items to submit the name. Currently, one item of type + KDBUS_ITEM_NAME is expected and allowed, and + the contained string must be a valid bus name. + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + + Releasing a name + + A connection may release a name explicitly with the + KDBUS_CMD_NAME_RELEASE ioctl. If the connection was + an implementer of an activatable name, its pending messages are moved + back to the activator. If there are any connections queued up as waiters + for the name, the first one in the queue (the oldest entry) will become + the new owner. The same happens implicitly for all names once a + connection terminates. See + kdbus.connection7 + for more information on connections. + + + The KDBUS_CMD_NAME_RELEASE ioctl uses the same data + structure as the acquisition call (KDBUS_CMD_NAME_ACQUIRE), + but with slightly different field usage. + + + +struct kdbus_cmd_name { + __u64 size; + The overall size of this struct, including the null-terminated name string. + + __u64 flags; + Flags to the command. Currently unused and must be zero. + + __u64 kernel_flags; + Valid flags for this command, returned by the kernel upon each call. + See section 3.2 for more details. + + __u64 return_flags; + Flags returned by the kernel. Currently unused and always set to zero by + the kernel. + + struct kdbus_item items[0]; + Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is + expected and allowed, and the contained string must be a valid bus name. +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + flags + + Flags to the command. Currently unused and must be zero. + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + + Items to submit the name. Currently, one item of type + KDBUS_ITEM_NAME is expected and allowed, and + the contained string must be a valid bus name. + + + Unrecognized items are rejected, and the ioctl will fail with + -EINVAL. + + + + + + + + Dumping the name registry + + A connection may request a complete or filtered dump of currently active + bus names with the KDBUS_CMD_NAME_LIST ioctl, which + takes a struct kdbus_cmd_name_list as argument. + + + +struct kdbus_cmd_name_list { + __u64 flags; + __u64 kernel_flags; + __u64 return_flags; + __u64 offset; +}; + + + The fields in this struct are described below. + + + + flags + + + Any combination of flags to specify which names should be dumped. + + + + KDBUS_NAME_LIST_UNIQUE + + + List the unique (numeric) IDs of the connection, whether it + owns a name or not. + + + + + + KDBUS_NAME_LIST_NAMES + + + List well-known names stored in the database which are + actively owned by a real connection (not an activator). + + + + + + KDBUS_NAME_LIST_ACTIVATORS + + + List names that are owned by an activator. + + + + + + KDBUS_NAME_LIST_QUEUED + + + List connections that are not yet owning a name but are + waiting for it to become available. + + + + + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + offset + + When the ioctl returns successfully, the offset to the name registry + dump inside the connection's pool will be stored in this field. + + + + + + The returned list of names is stored in a + struct kdbus_name_list that in turn + contains a dynamic number of + struct kdbus_cmd_name that carry the actual + information. The fields inside that + struct kdbus_cmd_name is described next. + + + +struct kdbus_name_info { + __u64 size; + __u64 owner_id; + __u64 conn_flags; + struct kdbus_item items[0]; +}; + + + The fields in this struct are described below. + + + + size + + The overall size of the struct, including its items. + + + + + owner_id + + The owning connection's unique ID. + + + + + conn_flags + + The flags of the owning connection. + + + + + flags + + + Items containing the actual name. Currently, one item of type + KDBUS_ITEM_OWNED_NAME will be attached, + including the name's flags. In that item, the flags field of the + name may carry the following bits: + + + + KDBUS_NAME_ALLOW_REPLACEMENT + + + Other connections are allowed to take over this name from the + connection that owns it. + + + + + + KDBUS_NAME_IN_QUEUE + + + When retrieving a list of currently acquired names in the + registry, this flag indicates whether the connection + actually owns the name or is currently waiting for it to + become available. + + + + + + KDBUS_NAME_ACTIVATOR + + + An activator connection owns a name as a placeholder for an + implementer, which is started on demand by userspace as soon + as the first message arrives. There's some more information + on this topic in + kdbus.connection7 + . + + + In contrast to KDBUS_NAME_REPLACE_EXISTING, + when a name is taken over from an activator connection, all + the messages that have been queued in the activator + connection will be moved over to the new owner. The activator + connection will still be tracked for the name and will take + control again if the implementer connection terminates. + + + This flag can not be used when acquiring a name, but is implicitly set + through KDBUS_CMD_HELLO with + KDBUS_HELLO_ACTIVATOR set in + kdbus_cmd_hello.conn_flags. + + + + + + + + + + + The returned buffer must be freed with the KDBUS_CMD_FREE ioctl when the user + is finished with it. See + kdbus.pool7 + for more information. + + + + + Return value + + On success, all metioned ioctl commands return 0. + + + + KDBUS_CMD_NAME_ACQUIRE may return the following errors. + + + + + -EINVAL + + Illegal command flags, illegal name provided, or an activator + tried to acquire a second name. + + + + + -EPERM + + Policy prohibited name ownership. + + + + + -EALREADY + + Connection already owns that name. + + + + + -EEXIST + + The name already exists and can not be taken over. + + + + + -E2BIG + + The maximum number of well-known names per connection is exhausted. + + + + + + KDBUS_CMD_NAME_RELEASE may return the following errors. + + + + + -EINVAL + + Invalid command flags, or invalid name provided. + + + + + -ESRCH + + Name is not found in the registry. + + + + + -EADDRINUSE + + Name is owned by a different connection and can't be released. + + + + + + KDBUS_CMD_NAME_LIST may return the following errors. + + + + + -EINVAL + + Invalid command flags + + + + + -ENOBUFS + + No available memory in the connection's pool. + + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.items7 + + + diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml new file mode 100644 index 0000000..167727f --- /dev/null +++ b/doc/kdbus.pool.xml @@ -0,0 +1,210 @@ + + + + + + + kdbus.pool + kdbus.pool + + + + kdbus.pool + 7 + + + + kdbus.pool + kdbus pool + + + + Description + + A pool for data received from the kernel is installed for every + connection of the bus, and + is sized according to the information stored in the + KDBUS_ITEM_BLOOM_PARAMETER item that is returned by + KDBUS_CMD_HELLO. + + + + The pool is written to by the kernel when one of the following + ioctls is issued: + + + + KDBUS_CMD_HELLO + + ... to receive details about the bus the connection was made to + + + + KDBUS_CMD_RECV + + ... to receive a message + + + + KDBUS_CMD_NAME_LIST + + ... to dump the name registry + + + + KDBUS_CMD_CONN_INFO + + ... to retrieve information on a connection + + + + + + + The offsets returned by either one of the aforementioned ioctls describe offsets + inside the pool. In order to make the slice available for subsequent calls, + KDBUS_CMD_FREE has to be called on the offset (see below). + + To access the memory, the caller is expected to + mmap2 + it, like this: + + +/* + * POOL_SIZE has to be a multiple of PAGE_SIZE, and it must match the + * value that was previously returned through the KDBUS_ITEM_BLOOM_PARAMETER + * item field when the KDBUS_CMD_HELLO ioctl returned. + */ + +buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); + + + + Alternatively, instead of mapping the entire pool buffer, only parts of it can + be mapped. The length of the response is returned by the kernel along with the + offset for each of the ioctls listed above. + + + + + Description + + TODO: some words about how slices are alllocated ... + + + + + Freeing pool slices + + The KDBUS_CMD_FREE ioctl is used to free a slice + inside the pool, described an offset that was returned in an 'offset' + field of another ioctl struct. The command takes a + struct kdbus_cmd_free as argument: + + + +struct kdbus_cmd_free { + __u64 size; + __u64 offset; + __u64 flags; + __u64 kernel_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. + + + + + offset + + The offset to free, as returned by other ioctls that allocated + memory for returned information. + + + + + kernel_flags + + Valid flags for this command, returned by the kernel upon each call. + + + + + return_flags + + Flags returned by the kernel. Currently unused and always set to + zero by the kernel. + + + + + items + + Items to specify further details for the receive command. + Currently unused. All items will be rejected with -EINVAL. + + + + + + + Return value + + On success, all metioned ioctl commands return 0. + + + + KDBUS_CMD_FREE may return the following errors. + + + + + -ENXIO + + No pool slice found at given offset. + + + + + -EINVAL + + Invalid flags provided. + + + + + -EINVAL + + The offset is valid, but the user is not allowed to free the slice. + This happens, for example, if the offset was retrieved with + KDBUS_RECV_PEEK. + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.items7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + diff --git a/doc/kdbus.xml b/doc/kdbus.xml new file mode 100644 index 0000000..cdbb7d4 --- /dev/null +++ b/doc/kdbus.xml @@ -0,0 +1,624 @@ + + + + + + + kdbus + kdbus + + + + Developer + David + Herrmann + dh.herrmann@gmail.com + + + + + + kdbus + 7 + + + + kdbus + Kernel Message Bus + + + + Description + + kdbus is an inter-process communication bus system + controlled by the kernel. It provides user-space with a bus API + to send unicast and multicast messages to one, or many, peers + connected to the same bus. + It does not enforce any layout on the transmitted data, but + only provides the transport layer used for message interchange + between peers. + + + + kdbus provides a pseudo file-system called + kdbusfs, which is usually mounted on + /sys/fs/kdbus. Buses and their endpoints + can be accessed as sub-directories and files underneath this + mount-point. Any advanced operations are done via + ioctl() on files created by + kdbusfs. Multiple mount-points of + kdbusfs are independent of each other. + This allows namespacing of kdbus by mounting a new instance of + kdbusfs in a mount-namespace. kdbus calls + these domains and each mount has its own kdbus domain, with + each bus being linked to exactly one parent domain. + + + + Please note that kdbus was designed as transport layer for D-Bus, but is + in no way limited, nor controlled by the D-Bus protocol specification. + The D-Bus protocol is one possible application layer on top of kdbus. + + + + For the general D-Bus protocol specification, the payload format, the + marshaling, and the communication semantics, please refer to the + + D-Bus specification. + + + + + + Terminology + + + Bus + + A bus is a named object inside a domain. Clients exchange messages + over a bus. Multiple buses themselves have no connection to each other; + messages can only be exchanged on the same bus. The default endpoint of + a bus, to which clients establish connections to, is the "bus" file + /sys/fs/kdbus/<bus name>/bus. + Common operating system setups create one "system bus" per system, + and one "user bus" for every logged-in user. Applications or services + may create their own private buses. The kernel driver does not + distinguish between different bus types, they are all handled the same + way. + See + kdbus.bus7 + for more details. + + + + + Endpoint + + An endpoint provides a file to talk to a bus. Opening an endpoint + creates a new connection to the bus to which the endpoint belongs. All + endpoints have unique names and are accessible as files underneath the + directory of a bus, e.g., /sys/fs/kdbus/<bus>/<endpoint> + Every bus has a default endpoint called "bus". + A bus can optionally offer additional endpoints with custom names + to provide restricted access to the bus. Custom endpoints carry + additional policy which can be used to create sandboxes with + locked-down, limited, filtered access to a bus. + See + kdbus.endpoint7 + for more details. + + + + + Connection + + A connection to a bus is created by opening an endpoint file of a + bus and becoming an active client with the HELLO + exchange. Every ordinary client connection has a unique identifier on + the bus and can address messages to every other connection on the same + bus by using the peer's connection ID as the destination. + See + kdbus.connection7 + for more details. + + + + + Pool + + Each connection allocates a piece of shmem-backed memory that is + used to receive messages and answers to ioctl commands from the kernel. + It is never used to send anything to the kernel. In order to access that + memory, a userspace application must mmap() it into its address space. + See section 12 for more details. + See + kdbus.pool7 + for more details. + + + + + Well-known Name + A connection can, in addition to its implicit unique connection ID, request + the ownership of a textual well-known name. Well-known names are noted in + reverse-domain notation, such as com.example.service1. A connection that + offers a service on a bus is usually reached by its well-known name. The + analogy of connection ID and well-known name is an IP address and a DNS + name associated with that address. + See + kdbus.names7 + for more details. + + + + + Message + + Connections can exchange messages with other connections by addressing + the peers with their connection ID or well-known name. A message consists + of a message header with information on how to route the message, and the + message payload, which is a logical byte stream of arbitrary size. + Messages can carry additional file descriptors to be passed from one + connection to another, just like passing file descriptors over UNIX domain + sockets. Every connection can specify which set of metadata the kernel + should attach to the message when it is delivered to the receiving + connection. Metadata contains information like: system timestamps, UID, GID, + TID, proc-starttime, well-known names, process comm, process exe, process + argv, cgroup, capabilities, seclabel, audit session, loginuid and the + connection's human-readable name. See section 7 and 13 for more details. + See + kdbus.message7 + for more details. + + + + + Item + + The API of kdbus implements the notion of items, submitted through and + returned by most ioctls, and stored inside data structures in the + connection's pool. See section 4 for more details. + See + kdbus.item7 + for more details. + + + + + Broadcast, signal, filter, match + + Signals are messages that a receiver opts in for by installing a blob of + bytes, called a 'match'. Signal messages must always carry a counter-part + blob, called a 'filter', and signals are only delivered to peers which have + a match that whitelists the message's filter. + Senders of signal messages can use either a single connection ID as + receiver, or KDBUS_DST_ID_BROADCAST to potentially send it to all + connections of a bus, following the logic described above. + See + kdbus.match7 and + kdbus.message7 + for more details. + + + + + Policy + + A policy is a set of rules that define which connections can see, talk to, + or register a well-known name on the bus. A policy is attached to buses and + custom endpoints, and modified by policy holder connections or owners of + custom endpoints. See section 11 for more details. + See + kdbus.policy7 + for more details. + + + + + Privileged bus users + + A user connecting to the bus is considered privileged if it is either the + creator of the bus, or if it has the CAP_IPC_OWNER capability flag set. + See + kdbus.connection7 + for more details. + + + + + + + The ioctl interface + + kdbus exposes its functions exclusively through + ioctl2 + through file descriptors returned by + open2 + on pseudo files exposed by + kdbus.fs7. + + + Following is a list of all the ioctls. + + +0x40209500 KDBUS_CMD_BUS_MAKE struct kdbus_cmd_make * +0x40209510 KDBUS_CMD_ENDPOINT_MAKE struct kdbus_cmd_make * +0xc0689520 KDBUS_CMD_HELLO struct kdbus_cmd_hello * +0x00009521 KDBUS_CMD_BYEBYE +0xc0489530 KDBUS_CMD_SEND struct kdbus_cmd_send * +0xc0489531 KDBUS_CMD_RECV struct kdbus_cmd_recv * +0x40289532 KDBUS_CMD_FREE struct kdbus_cmd_free * +0xc0209540 KDBUS_CMD_NAME_ACQUIRE struct kdbus_cmd_name * +0x40209541 KDBUS_CMD_NAME_RELEASE struct kdbus_cmd_name * +0xc0309542 KDBUS_CMD_NAME_LIST struct kdbus_cmd_name_list * +0xc0389550 KDBUS_CMD_CONN_INFO struct kdbus_cmd_info * +0x40209551 KDBUS_CMD_CONN_UPDATE struct kdbus_cmd_update * +0xc0389552 KDBUS_CMD_BUS_CREATOR_INFO struct kdbus_cmd_info * +0x40209561 KDBUS_CMD_ENDPOINT_UPDATE struct kdbus_cmd_update * +0x40289570 KDBUS_CMD_MATCH_ADD struct kdbus_cmd_match * +0x40289571 KDBUS_CMD_MATCH_REMOVE struct kdbus_cmd_match * + + + + These ioctls, along with the structs they transport, are explained in + detail in the other documents linked to in the 'see also' section below. + + + + + Data structures and interconnections + + + + + Bus Layout + + A bus + (kdbus.bus7) + provides and defines an environment that peers can connect to + for message interchange. A bus is created via the kdbus + control interface and can be modified by the bus creator. It + applies the policy that control all bus operations. The bus + creator itself does not participate as a peer. + To establish a peer connection + (kdbus.connection7), + you have to open one of the endpoints + (kdbus.endpoint7) + of a bus. Each bus provides a default endpoint, but further + endpoints can be created on-demand. Endpoints are used to apply + additional policies for all connections on this endpoint. Thus, + they provide additional filters to further restrict access of + specific connections to the bus. + + + + Following, you can see an example bus layout: + + + + + + + + Metadata + + kdbus records data about the system in certain situations. Such metadata + can refer to the currently active process (creds, PIDs, current user + groups, process names and its executable path, cgroup membership, + capabilities, security label and audit information), connection + information (description string, currently owned names) and timestamps. + + + Metadata is collected in the following circumstances. + + + + + When a bus is created (KDBUS_CMD_MAKE), information + about the calling task is collected. This data is returned by the + kernel via the KDBUS_CMD_BUS_CREATOR_INFO call. + + + + When a connection is created (KDBUS_CMD_HELLO), + information about the calling task is collected. Alternatively, a + privileged connection may provide 'faked' information about credentials, + PIDs and security labels which will be taken instead. This data is + returned by the kernel as information on a connection + (KDBUS_CMD_CONN_INFO). + + + + When a message is sent (KDBUS_CMD_SEND), information + about the sending task and the sending connection are collected. + This metadata will be attached to the message when it arrives in the + receiver's pool. If the connection sending the message installed faked + credentials (see + kdbus.connection7), + the message will not be augmented by any information about the + currently sending task. + + + + + Which metadata items are actually delivered depends on the following + sets and masks: + + + + + (a) the system-wide kmod creds mask + (module parameter attach_flags_mask) + + + + (b) the per-connection send creds mask, set by the connecting client + + + + (c) the per-connection receive creds mask, set by the connecting client + + + + (d) the per-bus minimal creds mask, set by the bus creator + + + + (e) the per-bus owner creds mask, set by the bus creator + + + + (f) the mask specified when querying creds of a bus peer + + + + (g) the mask specified when querying creds of a bus owner + + + + + With the following rules: + + + + + [1] The creds attached to messages are determined as + (a & b & c). + + + + [2] When connecting to a bus (KDBUS_CMD_HELLO), and + (~b & d) != 0, the call will fail, the connection is refused. + + + + [3] When querying creds of a bus peer, the creds returned are + (a & b & f) + + + + [4] When querying creds of a bus owner, the creds returned are + (a & e & g) + + + + [5] When creating a new bus, and (d & ~a) != 0, then bus creation + will fail + + + + + Hence, userspace might not always get all requested metadata items that + it requested. Code must be written so that it can cope with this fact. + + + + Known metadata item types + + To let the kernel know which metadata information to attach as items + to the afformentioned commands, it uses a bitmask. In those, the + following attach flags are currently supported. + + + + + KDBUS_ATTACH_TIMESTAMP + + Requests the attachment of an item of type + KDBUS_ITEM_TIMESTAMP. + + + + + KDBUS_ATTACH_CREDS + + Requests the attachment of an item of type + KDBUS_ITEM_CREDS. + + + + + KDBUS_ATTACH_PIDS + + Requests the attachment of an item of type + KDBUS_ITEM_PIDS. + + + + + KDBUS_ATTACH_AUXGROUPS + + Requests the attachment of an item of type + KDBUS_ITEM_AUXGROUPS. + + + + + KDBUS_ATTACH_NAMES + + Requests the attachment of an item of type + KDBUS_ITEM_OWNED_NAME. + + + + + KDBUS_ATTACH_TID_COMM [*] + + Requests the attachment of an item of type + KDBUS_ITEM_TID_COMM. + + + + + KDBUS_ATTACH_PID_COMM [*] + + Requests the attachment of an item of type + KDBUS_ITEM_PID_COMM. + + + + + KDBUS_ATTACH_EXE [*] + + Requests the attachment of an item of type + KDBUS_ITEM_EXE. + + + + + KDBUS_ATTACH_CMDLINE + + Requests the attachment of an item of type + KDBUS_ITEM_CMDLINE. + + + + + KDBUS_ATTACH_CGROUP + + Requests the attachment of an item of type + KDBUS_ITEM_CGROUP. + + + + + KDBUS_ATTACH_CAPS + + Requests the attachment of an item of type + KDBUS_ITEM_CAPS. + + + + + KDBUS_ATTACH_SECLABEL + + Requests the attachment of an item of type + KDBUS_ITEM_SECLABEL. + + + + + KDBUS_ATTACH_AUDIT + + Requests the attachment of an item of type + KDBUS_ITEM_AUDIT. + + + + + KDBUS_ATTACH_CONN_DESCRIPTION + + Requests the attachment of an item of type + KDBUS_ITEM_CONN_DESCRIPTION. + + + + + + Please refer to + kdbus.item7 + for detailed information about the layout any payload of items. + + + + [*] Note that the content stored in these items can easily be tampered + by the sending tasks. Therefore, they should not + be used for any sort of security relevant assumptions. The only reason + why they are transmitted is to let receivers know about details that + were set when metadata was collected, even though the task they were + collected from is not active any longer when the items are received. + + + + + + + See Also + + kdbus.bus7 + kdbus.connection7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + ioctl2 + mmap2 + open2 + close2 + D-Bus + + + + diff --git a/doc/stylesheet.xsl b/doc/stylesheet.xsl new file mode 100644 index 0000000..52565ea --- /dev/null +++ b/doc/stylesheet.xsl @@ -0,0 +1,16 @@ + + + 1 + ansi + 80 + 0 + A4 + 2 + 1 + 1 + + +