From: Daniel Mack Date: Wed, 28 Jan 2015 20:18:40 +0000 (+0100) Subject: doc: assorted fixup X-Git-Tag: upstream/0.20150129.081441utc~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=97d8d5b33951f026959a7a07481bdc909c751564;p=platform%2Fcore%2Fsystem%2Fkdbus-bus.git doc: assorted fixup Closed some TODOs in kdbus.item and lots of reformatting. Signed-off-by: Daniel Mack --- diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml index b2248e8..8914f42 100644 --- a/doc/kdbus.bus.xml +++ b/doc/kdbus.bus.xml @@ -23,8 +23,13 @@ Description - A bus is a resource that is shared between connections in order to transmit - messages (see kdbus.message7). + A bus is a resource that is shared between connections in order to + transmit messages (see + + kdbus.message + 7 + + ). Each bus is independent and operations on the bus will not have any effect on other buses. A bus is a management entity, that controls the addresses of its connections, their policies and message transactions @@ -33,8 +38,11 @@ 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 + + kdbus.fs + 7 + + , a bus is presented as a directory. No operations can be performed on the bus itself; instead you need to perform the operations on an endpoint associated with the bus. Endpoints are accessible as files underneath the bus directory. A default endpoint called "bus" is provided on each bus. @@ -61,15 +69,19 @@ 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 - close2 + + close + 2 + . - Each bus will generate a random, 128-bit UUID upon creation. This UUID will be - returned to creators of connections through kdbus_cmd_hello.id128 and can - be used 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 + 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. @@ -143,8 +155,11 @@ struct kdbus_cmd_make { The following items (see - kdbus.item7) - are expected for KDBUS_CMD_BUS_MAKE. + + kdbus.item + 7 + + ) are expected for KDBUS_CMD_BUS_MAKE. @@ -167,7 +182,10 @@ struct kdbus_cmd_make { struct kdbus_bloom_parameter. These settings are copied back to new connections verbatim. This item is mandatory. See - kdbus.item7 + + kdbus.item + 7 + for a more detailed description of this item. @@ -176,12 +194,14 @@ struct kdbus_cmd_make { 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. + + 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. @@ -203,7 +223,7 @@ struct kdbus_cmd_make { Unrecognized items are rejected, and the ioctl will fail with - errno set to EINVAL. + errno set to EINVAL. @@ -262,14 +282,54 @@ struct kdbus_cmd_make { See Also - kdbus7 - kdbus.connection7 - kdbus.endpoint7 - kdbus.fs7 - kdbus.item7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 + + + kdbus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml index 10f5ed9..270ecca 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -42,7 +42,10 @@ connections on the bus. However, in order to receive any broadcast messages, clients must subscribe to the specific messages they are interested in (see - kdbus.match7 + + kdbus.match + 7 + ). @@ -55,7 +58,10 @@ 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 + + kdbus.names + 7 + on name acquisition, the name registry, and the validity of names. @@ -118,11 +124,14 @@ Creating connections A connection to a bus is created by opening an endpoint file (see - kdbus.endpoint7) - of a bus and becoming an active client with the KDBUS_CMD_HELLO - ioctl. Every 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. + + kdbus.endpoint + 7 + + ) of a bus and becoming an active client with the + KDBUS_CMD_HELLO ioctl. Every 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. @@ -235,10 +244,11 @@ TODO: document precisely what combination of flags may be passed by the sender and that are requested by the receiver will be attached to the message. Note, however, that the bus may optionally require some of those bits to be set. If the match fails, the ioctl will fail - with errno set to -ECONNREFUSED. - In either case, when returning the field will be set to the mask of - metadata items that are enforced by the bus with the - KDBUS_FLAGS_KERNEL bit set as well. + with errno set to + ECONNREFUSED. In either case, when returning the + field will be set to the mask of metadata items that are enforced by + the bus with the KDBUS_FLAGS_KERNEL bit set as + well. @@ -247,9 +257,15 @@ TODO: document precisely what combination of flags may be passed Request the attachment of metadata for each message received by this connection. See - kdbus7 + + kdbus + 7 + for information about metadata, and - kdbus.item7 + + kdbus.item + 7 + regarding items in general. @@ -275,13 +291,19 @@ TODO: document precisely what combination of flags may be passed The size of the communication pool, in bytes. The pool can be accessed by calling - mmap2 + + mmap + 2 + on the file descriptor that was used to issue the KDBUS_CMD_HELLO ioctl. See - kdbus.pool7 + + kdbus.pool + 7 + for further information. @@ -327,7 +349,10 @@ TODO: document precisely what combination of flags may be passed For activators and policy holders only, combinations of these two items describe policy access entries. See - kdbus.policy7 + + kdbus.policy + 7 + for further details. @@ -351,7 +376,7 @@ TODO: document precisely what combination of flags may be passed Unrecognized items are rejected, and the ioctl will fail with - errno set to EINVAL. + errno set to EINVAL. @@ -377,7 +402,10 @@ TODO: document precisely what combination of flags may be passed The offset in the pool has to be freed with the KDBUS_CMD_FREE ioctl. See - kdbus.pool7 + + kdbus.pool + 7 + for further information. @@ -455,7 +483,10 @@ struct kdbus_cmd_info { Specifies which metadata items should be attached to the answer. See - kdbus.message7 + + kdbus.message + 7 + @@ -488,7 +519,10 @@ struct kdbus_cmd_info { When the ioctl returns, this field will contain the offset of the connection information inside the caller's pool. See - kdbus.pool7 + + kdbus.pool + 7 + for futher information. @@ -498,9 +532,15 @@ struct kdbus_cmd_info { The kernel will return the size of the returned information, so applications can optionally - mmap2 + + mmap + 2 + specific parts of the pool. See - kdbus.pool7 + + kdbus.pool + 7 + for futher information. @@ -526,7 +566,7 @@ struct kdbus_cmd_info { Unrecognized items are rejected, and the ioctl will fail with - errno set to EINVAL. + errno set to EINVAL. @@ -586,7 +626,10 @@ struct kdbus_info { 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 + + kdbus.pool + 7 + for futher information. @@ -603,8 +646,8 @@ struct kdbus_info { 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, + 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. @@ -656,7 +699,10 @@ struct kdbus_info { 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 + + kdbus.pool + 7 + for futher information. @@ -743,7 +789,8 @@ struct kdbus_cmd_update { Policy holder connections may supply a new set of policy information with these items. For other connection types, - EOPNOTSUPP is returned in errno. + EOPNOTSUPP is returned in + errno. @@ -751,7 +798,7 @@ struct kdbus_cmd_update { Unrecognized items are rejected, and the ioctl will fail with - errno set to EINVAL. + errno set to EINVAL. @@ -796,7 +843,10 @@ struct kdbus_cmd_update { Termination of connections A connection can be terminated by simply calling - close2 + + close + 2 + on its file descriptor. All pending incoming messages will be discarded, and the memory allocated by the pool will be freed. @@ -805,7 +855,7 @@ struct kdbus_cmd_update { 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, the ioctl will fail with errno set to + otherwise, the ioctl will fail with errno set to 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 @@ -984,13 +1034,42 @@ struct kdbus_cmd_update { See Also - kdbus7 - - kdbus.bus7 - kdbus.endpoint7 - kdbus.message7 - kdbus.pool7 - kdbus.items7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.message + 7 + + + + + kdbus.pool + 7 + + + + + kdbus.items + 7 + + diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml index b2bf61d..56a0cfd 100644 --- a/doc/kdbus.endpoint.xml +++ b/doc/kdbus.endpoint.xml @@ -24,42 +24,62 @@ Endpoints are entry points to a bus (see - kdbus.bus7). + + 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. + 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. + 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. + 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-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. + 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 bus. - To create connections to a bus, use KDBUS_CMD_HELLO on a file descriptor returned by - open2 - on an endpoint node. - See kdbus.connection7 + To create connections to a bus, use KDBUS_CMD_HELLO + on a file descriptor returned by + + open + 2 + + on an endpoint node. See + + kdbus.connection + 7 + for further details. @@ -70,9 +90,16 @@ 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.fs7, + + kdbus.fs + 7 + , the command also optionally takes items to set up the endpoint's - kdbus.policy7. + + kdbus.policy + 7 + + . KDBUS_CMD_ENDPOINT_MAKE takes a struct kdbus_cmd_make argument. @@ -154,14 +181,17 @@ struct kdbus_cmd_make { These items are used to set the policy attached to the endpoint. For more details on bus and endpoint policies, see - kdbus.policy7. + + kdbus.policy + 7 + . Unrecognized items are rejected, and the ioctl will fail with - errno set to EINVAL. + errno set to EINVAL. @@ -237,7 +267,10 @@ struct kdbus_cmd_make { These items are used to set the policy attached to the endpoint. For more details on bus and endpoint policies, see - kdbus.policy7. + + kdbus.policy + 7 + . Existing policy is atomically replaced with the new rules provided. @@ -292,7 +325,10 @@ struct kdbus_cmd_make { EPERM The calling user is not privileged. See - kdbus7 + + kdbus + 7 + for information about privileged users. @@ -332,14 +368,54 @@ struct kdbus_cmd_make { See Also - kdbus7 - kdbus.bus7 - kdbus.endpoint7 - kdbus.fs7 - kdbus.item7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + diff --git a/doc/kdbus.fs.xml b/doc/kdbus.fs.xml index 2b7d6cc..44c70d5 100644 --- a/doc/kdbus.fs.xml +++ b/doc/kdbus.fs.xml @@ -45,9 +45,18 @@ custom endpoints for the bus with KDBUS_CMD_ENDPOINT_MAKE. See - kdbus.bus7, - kdbus.connection7 and - kdbus.endpoint7 + + kdbus.bus + 7 + , + + kdbus.connection + 7 + and + + kdbus.endpoint + 7 + for more details. @@ -81,11 +90,36 @@ See Also - kdbus7 - kdbus.bus7 - kdbus.connection7 - kdbus.endpoint7 - mount8 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + mount + 8 + + diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml index a18f40a..9f8ed9c 100644 --- a/doc/kdbus.item.xml +++ b/doc/kdbus.item.xml @@ -42,8 +42,8 @@ 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 - attached to will cause the ioctl to fail with errno set to - EINVAL. + attached to will cause the ioctl to fail with errno + set to 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 @@ -66,9 +66,9 @@ The kernel expects all items to be aligned to 8-byte boundaries. Unaligned items will cause the ioctl they are used with to fail - with errno set to EINVAL. An item that has an - unaligned size itself hence needs to be padded if it is followed by - another item. + with errno set to EINVAL. + An item that has an unaligned size itself hence needs to be padded + if it is followed by another item. @@ -156,7 +156,10 @@ struct kdbus_item { Messages are directly copied by the sending process into the receiver's - kdbus.pool7. + + kdbus.pool + 7 + . 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_ITEM_PAYLOAD_VEC @@ -165,10 +168,16 @@ struct kdbus_item { KDBUS_ITEM_PAYLOAD_OFF is used when messages are received, and the offset value describes the offset inside the receiving connection's - kdbus.pool7 + + kdbus.pool + 7 + where the message payload can be found. See - kdbus.message7 + + kdbus.message + 7 + for more information on passing of payload data along with a message. @@ -192,7 +201,10 @@ struct kdbus_vec { the memfd that was specified when it was created. The start parameter denotes the offset inside the memfd at which the referenced payload starts. See - kdbus.message7 + + kdbus.message + 7 + for more information on passing of payload data along with a message. @@ -218,7 +230,10 @@ struct kdbus_memfd { filedescriptor. In either case, the number of entries in the array is derived from the item's total size. See - kdbus.message7 + + kdbus.message + 7 + for more information. @@ -236,14 +251,31 @@ struct kdbus_memfd { writing to it. The file descriptor is stored in item.fd[0]. The item may only contain one filedescriptor. See - kdbus.message7 + + kdbus.message + 7 + for more information on this item and how to use it. KDBUS_ITEM_BLOOM_PARAMETER - TODO + + Contains a set of bloom parameters as + struct kdbus_bloom_parameter in + item.bloom_parameter. + The item is passed from userspace to kernel during the + KDBUS_CMD_BUS_MAKE ioctl, and returned + verbatim when KDBUS_CMD_HELLO is called. + The kernel does not use the bloom parameters, but they need to + be known by each connection on the bus in order to define the + bloom filter hash details. See + + kdbus.match + 7 + + for more information on matching and bloom filters. struct kdbus_bloom_parameter { __u64 size; @@ -255,7 +287,18 @@ struct kdbus_bloom_parameter { KDBUS_ITEM_BLOOM_FILTER - TODO + + Carries a bloom filter as + struct kdbus_bloom_filter in + item.bloom_filter. It is mandatory to send this + item attached to a struct kdbus_msg, in case the + message is a signal. This item is never transported from kernel to + userspace. See + + kdbus.match + 7 + + for more information on matching and bloom filters. struct kdbus_bloom_filter { __u64 generation; @@ -267,7 +310,15 @@ struct kdbus_bloom_filter { KDBUS_ITEM_BLOOM_MASK - TODO + + Transports a bloom mask as binary data blob + stored in item.data. This item is used to + describe a match into a connection's match database. See + + kdbus.match + 7 + + for more information on matching and bloom filters. @@ -278,14 +329,32 @@ struct kdbus_bloom_filter { message to, as null-terminated string in item.str. This item is used with KDBUS_CMD_SEND. See - kdbus.message7 + + kdbus.message + 7 + for more information on how to send a message. KDBUS_ITEM_MAKE_NAME - TODO + + Contains a bus name or + endpoint name, stored as null-terminated + string in item.str. This item is sent from + userspace to kernel when buses or endpoints are created, and + returned back to userspace when the bus creator information is + queried. See + + kdbus.bus + 7 + + and + + kdbus.endpoint + 7 + . @@ -295,9 +364,18 @@ struct kdbus_bloom_filter { Contains a set of attach flags at send or receive time. See - kdbus7, - kdbus.bus7 and - kdbus.connection7 + + kdbus + 7 + , + + kdbus.bus + 7 + and + + kdbus.connection + 7 + for more information on attach flags. @@ -319,7 +397,10 @@ struct kdbus_bloom_filter { struct kdbus_name in item.name. The flags contains the flags of the name. See - kdbus.name7 + + kdbus.name + 7 + for more information on how to access the name registry of a bus. struct kdbus_name { @@ -532,7 +613,10 @@ struct kdbus_audit { All metadata is automatically translated into the namespaces of the task that receives them. See - kdbus.message7 + + kdbus.message + 7 + for more information. @@ -560,10 +644,19 @@ struct kdbus_audit { This item describes a policy access entry to access the policy database of a - kdbus.bus7 or - kdbus.endpoint7. + + kdbus.bus + 7 + or + + kdbus.endpoint + 7 + . Please refer to - kdbus.policy7 + + kdbus.policy + 7 + for more information on the policy database and how to access it. struct kdbus_policy_access { @@ -576,28 +669,72 @@ struct kdbus_policy_access { - KDBUS_ITEM_NAME_ADD - KDBUS_ITEM_NAME_REMOVE - KDBUS_ITEM_NAME_CHANGE - TODO + KDBUS_ITEM_ID_ADD + KDBUS_ITEM_ID_REMOVE + + This item is sent as attachment to a + kernel notification and indicates that a + new connection was created on the bus, or that a connection was + disconnected, respectively. It stores a + struct kdbus_notify_id_change in + item.id_change. + The id field contains the numeric ID of the + connection that was added or removed, and flags + is set to the connection flags, as passed by + KDBUS_CMD_HELLO. + See + + kdbus.match + 7 + + and + + kdbus.message + 7 + + for more information on matches and notification messages. -struct kdbus_notify_name_change { - struct kdbus_notify_id_change old_id; - struct kdbus_notify_id_change new_id; - char name[0]; +struct kdbus_notify_id_change { + __u64 id; + __u64 flags; }; - KDBUS_ITEM_ID_ADD - KDBUS_ITEM_ID_REMOVE - TODO + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE + + This item is sent as attachment to a + kernel notification and indicates that a + well-known name appeared, disappeared or + transferred to another owner on the bus. It stores a + struct kdbus_notify_name_change in + item.name_change. + old_id describes the former owner of the name + and is set to 0 values in case of + KDBUS_ITEM_NAME_ADD. + new_id describes the new owner of the name and + is set to 0 values in case of + KDBUS_ITEM_NAME_REMOVE. + See + + kdbus.match + 7 + + and + + kdbus.message + 7 + + for more information on matches and notification messages. -struct kdbus_notify_id_change { - __u64 id; - __u64 flags; +struct kdbus_notify_name_change { + struct kdbus_notify_id_change old_id; + struct kdbus_notify_id_change new_id; + char name[0]; }; @@ -605,13 +742,33 @@ struct kdbus_notify_id_change { KDBUS_ITEM_REPLY_TIMEOUT - TODO + + This item is sent as attachment to a + kernel notification. It informs the receiver + that an expected reply to a message was not received in time. + The remote peer ID and the message cookie is stored in the message + header. See + + kdbus.message + 7 + + for more information about messages, timeouts and notifications. KDBUS_ITEM_REPLY_DEAD - TODO + + This item is sent as attachment to a + kernel notification. It informs the receiver + that a remote connection a reply is expected from was disconnected + before that reply was sent. The remote peer ID and the message + cookie is stored in the message header. See + + kdbus.message + 7 + + for more information about messages, timeouts and notifications. @@ -621,14 +778,54 @@ struct kdbus_notify_id_change { See Also - kdbus7 - kdbus.bus7 - kdbus.connection7 - kdbus.endpoint7 - kdbus.fs7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml index 90273a4..1f2f52f 100644 --- a/doc/kdbus.match.xml +++ b/doc/kdbus.match.xml @@ -37,17 +37,20 @@ the connection, no broadcast message or kernel-side notifications will be delivered to the connection. Broadcast messages are subject to policy rules and TALK access checks - see - kdbus.policy7 + + kdbus.policy + 7 + for more details on implicit policies. Matches for messages from other connections (not kernel notifications) are - implemented as bloom filters. The sender adds certain properties of the message - as elements to a bloom filter bit field, and sends that along with the - broadcast message. + implemented as bloom filters. The sender adds certain properties of the + message as elements to a bloom filter bit field, and sends that along with + the broadcast message. - The connection adds the message properties it is interested as elements to a - bloom mask bit field, and uploads the mask to the match rules of the + The connection adds the message properties it is interested as elements to + a bloom mask bit field, and uploads the mask to the match rules of the connection. The kernel will match the broadcast message's bloom filter against the @@ -57,18 +60,19 @@ The kernel has no notion of any specific properties of the message, all it sees are the bit fields of the bloom filter and mask to match against. The - use of bloom filters allows simple and efficient matching, without exposing - any message properties or internals to the kernel side. Clients need to deal - with the fact that they might receive broadcasts which they did not subscribe - to, as the bloom filter might allow false-positives to pass the filter. - - To allow the future extension of the set of elements in the bloom filter, the - filter specifies a "generation" number. A later generation must always contain - all elements of the set of the previous generation, but can add new elements - to the set. The match rules mask can carry an array with all previous - generations of masks individually stored. When the filter and mask are matched - by the kernel, the mask with the closest matching "generation" is selected - as the index into the mask array. + use of bloom filters allows simple and efficient matching, without + exposing any message properties or internals to the kernel side. Clients + need to deal with the fact that they might receive broadcasts which they + did not subscribe to, as the bloom filter might allow false-positives to + pass the filter. + + To allow the future extension of the set of elements in the bloom filter, + the filter specifies a "generation" number. A later generation must always + contain all elements of the set of the previous generation, but can add + new elements to the set. The match rules mask can carry an array with all + previous generations of masks individually stored. When the filter and + mask are matched by the kernel, the mask with the closest matching + "generation" is selected as the index into the mask array. @@ -76,7 +80,10 @@ Matches for kernel notifications To receive kernel generated notifications (see - kdbus.message7 + + kdbus.message + 7 + ), a connection must install special match rules that are different from the bloom filter matches described in the section above. They can be filtered by a sender connection's ID, by one of the name the sender @@ -91,15 +98,18 @@ To add a match, the KDBUS_CMD_MATCH_ADD ioctl is used, which takes a struct of the struct described below. - Note that each of the items attached to this command will internally create - one match 'rule', and the collection of them, which is submitted as one block - via the ioctl, is called a 'match'. To allow a message to pass, all rules of a - match have to be satisfied. Hence, adding more items to the command will only - narrow the possibility of a match to effectively let the message pass, and will - decrease the chance that the connection's userspace process wil be woken up. - - Multiple matches can be installed per connection. As long as one of it has a - set of rules which allows the message to pass, this one will be decisive. + Note that each of the items attached to this command will internally + create one match rule, and the collection of them, + which is submitted as one block via the ioctl, is called a + match. To allow a message to pass, all rules of a + match have to be satisfied. Hence, adding more items to the command will + only narrow the possibility of a match to effectively let the message + pass, and will decrease the chance that the connection's userspace process + wil be woken up. + + Multiple matches can be installed per connection. As long as one of it has + a set of rules which allows the message to pass, this one will be + decisive. @@ -236,7 +246,7 @@ struct kdbus_cmd_match { Unrecognized items are rejected, and the ioctl will fail with - errno set to -EINVAL. + errno set to -EINVAL. @@ -244,7 +254,10 @@ struct kdbus_cmd_match { Refer to - kdbus.message7 + + kdbus.message + 7 + for more information on message types. @@ -453,14 +466,54 @@ struct kdbus_cmd_match { See Also - kdbus7 - kdbus.bus7 - kdbus.match7 - kdbus.fs7 - kdbus.item7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.match + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index c4a983f..289a9d7 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -134,14 +134,20 @@ struct kdbus_cmd_send { executed as SYNC call, the passed in file descriptor can be used as alternative cancellation point. The kernel will call poll() - poll2 + + poll + 2 + on this file descriptor, and if it reports any incoming bytes, the blocking send operation will be canceled, and the call will return -1 and errno will be set to ECANCELED. Any type of file descriptor on which - poll2 + + poll + 2 + can be called on can be used as payload to this item. For asynchronous message sending, this item is allowed but ignored. @@ -223,7 +229,8 @@ struct kdbus_msg { 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, the ioctl will fail - with errno set to EADDRNOTAVAIL. + with errno set to + EADDRNOTAVAIL. @@ -289,7 +296,10 @@ struct kdbus_msg { 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. + + clock_gettime + 2 + . @@ -338,14 +348,15 @@ struct kdbus_msg { dst_id is set to KDBUS_DST_ID_NAME. If a connection holding the given name can't be found, - the ioctl will fail with errno set to - -ESRCH is returned. + the ioctl will fail with errno set to + 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. + 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. @@ -357,8 +368,15 @@ struct kdbus_msg { The message will be augmented by the requested metadata items when queued into the receiver's pool. See - kdbus.connection7 and - kdbus.item7 + + kdbus.connection + 7 + + and + + kdbus.item + 7 + for more information on metadata. @@ -416,7 +434,10 @@ struct kdbus_msg { See - kdbus.pool7 + + kdbus.pool + 7 + for more information. @@ -576,19 +597,19 @@ struct kdbus_cmd_recv { 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, the ioctl will fail, and errno will be set to - ENOMSG. + waiting in the queue, the ioctl will fail, and + errno will be set to ENOMSG. dropped_msgs - If the CMD_RECV ioctl fails with errno set to - 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. + If the CMD_RECV ioctl fails with + errno set to 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. @@ -632,10 +653,13 @@ struct kdbus_msg_info { offset - Upon return of the ioctl, this field contains the offset in the receiver's - memory pool. The memory must be freed with + 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 + + kdbus.pool + 7 + for further details. @@ -649,7 +673,10 @@ struct kdbus_msg_info { 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 + + kdbus.pool + 7 + for further details. @@ -867,7 +894,10 @@ struct kdbus_msg_info { 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. + + mmap + 2 + . @@ -1034,20 +1064,90 @@ struct kdbus_msg_info { 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 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.items + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + + + + clock_gettime + 2 + + + + + ioctl + 2 + + + + + poll + 2 + + + + + select + 2 + + + + + epoll + 7 + + diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml index aa8e346..5736bd0 100644 --- a/doc/kdbus.names.xml +++ b/doc/kdbus.names.xml @@ -23,7 +23,10 @@ Description Each - kdbus.bus7 + + kdbus.bus + 7 + 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 @@ -34,7 +37,10 @@ All of the below is subject to policy rules for SEE and OWN permissions. See - kdbus.policy7 + + kdbus.policy + 7 + for more information. @@ -46,26 +52,42 @@ - - 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) - + + + 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 255 characters in + length. + + @@ -110,7 +132,10 @@ struct kdbus_cmd_name { 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.connection + 7 + ). @@ -186,12 +211,16 @@ struct kdbus_cmd_name { 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 + + kdbus.connection + 7 + for more information on connections. The KDBUS_CMD_NAME_RELEASE ioctl uses the same data - structure as the acquisition call (KDBUS_CMD_NAME_ACQUIRE), + structure as the acquisition call + (KDBUS_CMD_NAME_ACQUIRE), but with slightly different field usage. @@ -258,7 +287,7 @@ struct kdbus_cmd_name { Unrecognized items are rejected, and the ioctl will fail with - errno set to -EINVAL. + errno set to EINVAL. @@ -440,7 +469,10 @@ struct kdbus_name_info { 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 + + kdbus.connection + 7 + . @@ -466,9 +498,13 @@ struct kdbus_name_info { - The returned buffer must be freed with the KDBUS_CMD_FREE ioctl when the user - is finished with it. See - kdbus.pool7 + The returned buffer must be freed with the + KDBUS_CMD_FREE ioctl when the user is finished with + it. See + + kdbus.pool + 7 + for more information. @@ -574,9 +610,24 @@ struct kdbus_name_info { See Also - kdbus7 - kdbus.bus7 - kdbus.items7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.items + 7 + + diff --git a/doc/kdbus.policy.xml b/doc/kdbus.policy.xml index bd7ad45..1bf0f98 100644 --- a/doc/kdbus.policy.xml +++ b/doc/kdbus.policy.xml @@ -35,7 +35,10 @@ KDBUS_CMD_HELLO When creating, or updating, a policy holder connection. See - kdbus.connection7. + + kdbus.connection + 7 + . @@ -44,7 +47,10 @@ KDBUS_CMD_ENDPOINT_UPDATE When creating, or updating, a bus custom endpoint. See - kdbus.endpoint7. + + kdbus.endpoint + 7 + . @@ -82,13 +88,19 @@ Names passed in items of type KDBUS_ITEM_NAME must comply to the rules of valid kdbus names. See - kdbus.names7 + + kdbus.names + 7 + for more information. The payload of an item of type KDBUS_ITEM_POLICY_ACCESS is defined by the following struct. For more information on the layout of items, please refer to - kdbus.item7. + + kdbus.item + 7 + . @@ -183,7 +195,10 @@ struct kdbus_policy_access { All endpoints of buses have an empty policy database by default. Therefore, unless policy rules are added, all operations will also be denied by default. Also see - kdbus.endpoint7. + + kdbus.endpoint + 7 + . @@ -212,7 +227,10 @@ struct kdbus_policy_access { The policy database is overruled when action is taken by a privileged connection. Please refer to - kdbus.connection7 + + kdbus.connection + 7 + for more information on what makes a connection privileged. @@ -247,23 +265,24 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK TALK access and multiple well-known names per connection - Note that TALK access is checked against all names of a connection. - For example, if a connection owns both 'org.foo.bar' and 'org.blah.baz', and - the policy database allows 'org.blah.baz' to be talked to by WORLD, then this - permission is also granted to 'org.foo.bar'. That might sound illogical, but - after all, we allow messages to be directed to either the ID or a well-known - name, and policy is applied to the connection, not the name. In other words, - the effective TALK policy for a connection is the most permissive of all names - the connection owns. - - For broadcast messages, the receiver needs TALK permissions to the sender to - receive the broadcast. + Note that TALK access is checked against all names of a connection. For + example, if a connection owns both 'org.foo.bar' and + 'org.blah.baz', and the policy database allows + 'org.blah.baz' to be talked to by WORLD, then this + permission is also granted to 'org.foo.bar'. That + might sound illogical, but after all, we allow messages to be directed to + either the ID or a well-known name, and policy is applied to the + connection, not the name. In other words, the effective TALK policy for a + connection is the most permissive of all names the connection owns. + + For broadcast messages, the receiver needs TALK permissions to the sender + to receive the broadcast. Both the endpoint and the bus policy databases are consulted to allow name registry listing, owning a well-known name and message delivery. - If either one fails, the operation is failed with errno set to - EPERM. + If either one fails, the operation is failed with + errno set to EPERM. For best practices, connections that own names with a restricted TALK access should not install matches. This avoids cases where the sent @@ -271,7 +290,10 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK satisfy the policy rules. Also see - kdbus.match7. + + kdbus.match + 7 + . @@ -308,8 +330,8 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK - Policy rules are always enforced, even if the connection is a privileged - connection. + Policy rules are always enforced, even if the connection is a + privileged connection. @@ -331,14 +353,54 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK See Also - kdbus7 - kdbus.bus7 - kdbus.endpoint7 - kdbus.fs7 - kdbus.item7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index 173c60d..8fa2a86 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -77,7 +77,10 @@ Memory is the pool is read-only for userspace and may only be written to by the kernel. To read from the pool memory, the caller is expected to - mmap2 + + mmap + 2 + the buffer into its task, like this: @@ -87,7 +90,7 @@ * item field when the KDBUS_CMD_HELLO ioctl returned. */ -buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); +uint8_t *buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); @@ -95,7 +98,10 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); the one that was used to create the connection In other words, the one that was used to call KDBUS_CMD_HELLO. See - kdbus.connection7 + + kdbus.connection + 7 + for more details. @@ -121,8 +127,15 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); Pool slices are allocated by the kernel in order to report information back to a userspace task, such as messages, returned name list etc. Allocation of pool slices cannot be initiated by userspace. See - kdbus.connection7 and - kdbus.names7 + + kdbus.connection + 7 + + and + + kdbus.names + 7 + for examples of commands that use the pool to return data. @@ -234,13 +247,48 @@ struct kdbus_cmd_free { See Also - kdbus7 - kdbus.bus7 - kdbus.connection7 - kdbus.endpoint7 - kdbus.names7 - mmap2 - munmap2 + + + kdbus + 7 + + + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.names + 7 + + + + + mmap + 2 + + + + + munmap + 2 + + diff --git a/doc/kdbus.xml b/doc/kdbus.xml index b769824..2b85b5d 100644 --- a/doc/kdbus.xml +++ b/doc/kdbus.xml @@ -87,7 +87,10 @@ distinguish between different bus types, they are all handled the same way. See - kdbus.bus7 + + kdbus.bus + 7 + for more details. @@ -105,7 +108,10 @@ additional policy which can be used to create sandboxes with locked-down, limited, filtered access to a bus. See - kdbus.endpoint7 + + kdbus.endpoint + 7 + for more details. @@ -119,7 +125,10 @@ 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 + + kdbus.connection + 7 + for more details. @@ -132,21 +141,27 @@ 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 - kdbus.pool7 + + kdbus.pool + 7 + 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 + + 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.names + 7 + for more details. @@ -155,19 +170,22 @@ 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 - kdbus.message7 + 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 + + kdbus.message + 7 + for more details. @@ -179,7 +197,10 @@ returned by most ioctls, and stored inside data structures in the connection's pool. See - kdbus.item7 + + kdbus.item + 7 + for more details. @@ -188,15 +209,21 @@ 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 + 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.match + 7 + + and + + kdbus.message + 7 + for more details. @@ -204,12 +231,14 @@ 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 - kdbus.policy7 + 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 + + kdbus.policy + 7 + for more details. @@ -217,10 +246,13 @@ 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 + 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.connection + 7 + for more details. @@ -230,12 +262,22 @@ The ioctl interface - kdbus exposes its functions exclusively through - ioctl2 + + kdbus exposes its functions exclusively through + + ioctl + 2 + through file descriptors returned by - open2 + + open + 2 + on pseudo files exposed by - kdbus.fs7. + + kdbus.fs + 7 + . Following is a list of all the ioctls. @@ -303,21 +345,17 @@ 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 + + A bus 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, you have to open one of the + endpoints 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. @@ -378,12 +416,15 @@ - 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), + 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.connection + 7 + ), the message will not be augmented by any information about the currently sending task. @@ -585,7 +626,10 @@ Please refer to - kdbus.item7 + + kdbus.item + 7 + for detailed information about the layout and payload of items and what metadata should be used to. @@ -596,19 +640,81 @@ See Also - kdbus.bus7 - kdbus.connection7 - kdbus.endpoint7 - kdbus.fs7 - kdbus.item7 - kdbus.message7 - kdbus.names7 - kdbus.pool7 - ioctl2 - mmap2 - open2 - close2 - D-Bus + + + kdbus.bus + 7 + + + + + kdbus.connection + 7 + + + + + kdbus.endpoint + 7 + + + + + kdbus.fs + 7 + + + + + kdbus.item + 7 + + + + + kdbus.message + 7 + + + + + kdbus.names + 7 + + + + + kdbus.pool + 7 + + + + + ioctl + 2 + + + + + mmap + 2 + + + + + open + 2 + + + + + close + 2 + + + + D-Bus +