From 4adbd45592e782cd7342012aff704eee618d1e67 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Wed, 28 Jan 2015 17:26:13 +0100 Subject: [PATCH] doc: more tag cleanups Signed-off-by: Daniel Mack --- doc/kdbus.bus.xml | 72 ++++++++++--------- doc/kdbus.connection.xml | 147 ++++++++++++++++++++------------------- doc/kdbus.endpoint.xml | 36 +++++----- doc/kdbus.fs.xml | 8 +-- doc/kdbus.item.xml | 57 +++++++-------- doc/kdbus.match.xml | 56 +++++++-------- doc/kdbus.message.xml | 26 +++---- doc/kdbus.names.xml | 70 +++++++++---------- doc/kdbus.policy.xml | 65 ++++++++--------- doc/kdbus.pool.xml | 22 +++--- doc/kdbus.xml | 78 ++++++++++----------- 11 files changed, 326 insertions(+), 311 deletions(-) diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml index 8b1412c..52ae9f2 100644 --- a/doc/kdbus.bus.xml +++ b/doc/kdbus.bus.xml @@ -27,12 +27,12 @@ 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. + 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 + 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 @@ -41,23 +41,28 @@ 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. + 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 bus owner. - To create a new bus, you need to open the control file of a domain and employ - the KDBUS_CMD_BUS_MAKE ioctl. The control file descriptor that was used to issue - KDBUS_CMD_BUS_MAKE must not previously have been used for any other - control-ioctl and must be kept open for the entire life-time of the created - bus. Closing it will immediately cleanup the entire bus and all its associated - resources and endpoints. Every control file descriptor can only be used to - create a single new bus; from that point on, it is not used for any further - communication until the final close(). + 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 + close2 + . Each bus will generate a random, 128-bit UUID upon creation. This UUID will be @@ -74,8 +79,8 @@ 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. + 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 { @@ -102,14 +107,14 @@ struct kdbus_cmd_make { The flags for creation. - KDBUS_MAKE_ACCESS_GROUP + KDBUS_MAKE_ACCESS_GROUP Make the bus or endpoint file group-accessible - KDBUS_MAKE_ACCESS_WORLD + KDBUS_MAKE_ACCESS_WORLD Make the bus or endpoint file world-accessible @@ -139,11 +144,11 @@ struct kdbus_cmd_make { The following items (see kdbus.item7) - are expected for KDBUS_CMD_BUS_MAKE. + are expected for KDBUS_CMD_BUS_MAKE. - KDBUS_ITEM_MAKE_NAME + KDBUS_ITEM_MAKE_NAME Contains a null-terminated string that identifies the @@ -155,22 +160,21 @@ struct kdbus_cmd_make { - KDBUS_ITEM_BLOOM_PARAMETER + KDBUS_ITEM_BLOOM_PARAMETER Bus-wide bloom parameters passed in a - struct kdbus_bloom_parameter. These - settings are copied back to new connections verbatim. - This item is mandatory. - See + struct kdbus_bloom_parameter. These settings are + copied back to new connections verbatim. This item is + mandatory. See kdbus.item7 - for a detailed description of this item. + for a more detailed description of this item. - KDBUS_ITEM_ATTACH_FLAGS_RECV + 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 @@ -183,7 +187,7 @@ struct kdbus_cmd_make { - KDBUS_ITEM_ATTACH_FLAGS_SEND + KDBUS_ITEM_ATTACH_FLAGS_SEND An optional item that contains a set of attach flags that are @@ -199,7 +203,7 @@ struct kdbus_cmd_make { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to EINVAL. diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml index 1804df9..41d20ec 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -24,7 +24,7 @@ Connections are identified by their connection ID, - internally implemented as a uint64_t counter. + 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. @@ -34,21 +34,23 @@ ":1.<ID>". - Messages with a specific uint64_t destination ID are + 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 - (~0ULL) 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 they - are interested in (see - kdbus.match7). + with the special destination ID + KDBUS_DST_ID_BROADCAST (~0ULL) 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 they are + interested in (see + kdbus.match7 + ). Messages synthesized and sent directly by the kernel will carry the special - source ID KDBUS_SRC_ID_KERNEL (0). + source ID KDBUS_SRC_ID_KERNEL (0). - In addition to the unique uint64_t connection ID, + 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 @@ -57,9 +59,10 @@ on name acquisition, the name registry, and the validity of names. - Messages can specify the special destination ID KDBUS_DST_ID_NAME - (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. + Messages can specify the special destination ID + KDBUS_DST_ID_NAME (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. 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 + 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. @@ -158,23 +161,23 @@ struct kdbus_cmd_hello { TODO: document precisely what combination of flags may be passed - KDBUS_HELLO_ACCEPT_FD + KDBUS_HELLO_ACCEPT_FD When this flag is set, the connection can be sent file descriptors as message payload of unicast messages. If it's not set, an attempt to send file descriptors results in - -ECOMM on the sender's side. + -ECOMM on the sender's side. - KDBUS_HELLO_ACTIVATOR + KDBUS_HELLO_ACTIVATOR Make this connection an activator (see below). With this bit - set, an item of type KDBUS_ITEM_NAME has + 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. @@ -182,11 +185,11 @@ TODO: document precisely what combination of flags may be passed - KDBUS_HELLO_POLICY_HOLDER + KDBUS_HELLO_POLICY_HOLDER Make this connection a policy holder (see below). With this - bit set, an item of type KDBUS_ITEM_NAME + 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. @@ -194,7 +197,7 @@ TODO: document precisely what combination of flags may be passed - KDBUS_HELLO_MONITOR + KDBUS_HELLO_MONITOR Make this connection a monitor (eavesdropping) connection. @@ -231,10 +234,11 @@ TODO: document precisely what combination of flags may be passed receiving peer. Only metadata items that are both allowed to be sent 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, -ECONNREFUSED - will be returned. 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. + 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. @@ -273,7 +277,7 @@ TODO: document precisely what combination of flags may be passed accessed by calling mmap2 on the file descriptor that was used to issue the - KDBUS_CMD_HELLO ioctl. + KDBUS_CMD_HELLO ioctl. See @@ -307,7 +311,7 @@ TODO: document precisely what combination of flags may be passed - KDBUS_ITEM_CONN_DESCRIPTION + KDBUS_ITEM_CONN_DESCRIPTION Contains a string that describes this connection, so it can @@ -317,8 +321,8 @@ TODO: document precisely what combination of flags may be passed - KDBUS_ITEM_NAME - KDBUS_ITEM_POLICY_ACCESS + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS For activators and policy holders only, combinations of @@ -330,15 +334,15 @@ TODO: document precisely what combination of flags may be passed - KDBUS_ITEM_CREDS - KDBUS_ITEM_PIDS - KDBUS_ITEM_SECLABEL + 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 + KDBUS_CMD_CONN_INFO. See below for more information on retrieving information on connections. @@ -347,7 +351,7 @@ TODO: document precisely what combination of flags may be passed Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to EINVAL. @@ -355,13 +359,13 @@ TODO: document precisely what combination of flags may be passed At the offset returned in the offset field of - struct kdbus_cmd_hello, the kernel will store items + struct kdbus_cmd_hello, the kernel will store items of the following types: - KDBUS_ITEM_BLOOM_PARAMETER + KDBUS_ITEM_BLOOM_PARAMETER Bloom filter parameter as defined by the bus creator. @@ -372,7 +376,7 @@ 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_CMD_FREE ioctl. See kdbus.pool7 for further information. @@ -383,8 +387,8 @@ TODO: document precisely what combination of flags may be passed 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. + task had CAP_IPC_OWNER set when it called + KDBUS_CMD_HELLO. Privileged connections have permission to employ certain restricted @@ -420,9 +424,9 @@ TODO: document precisely what combination of flags may be passed 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. + 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. @@ -475,7 +479,7 @@ struct kdbus_cmd_info { 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. + KDBUS_ITEM_OWNED_NAME item is ignored. @@ -506,11 +510,11 @@ struct kdbus_cmd_info { The following items are expected for - KDBUS_CMD_CONN_INFO. + KDBUS_CMD_CONN_INFO. - KDBUS_ITEM_OWNED_NAME + KDBUS_ITEM_OWNED_NAME Contains the well-known name of the connection to look up as. @@ -522,7 +526,7 @@ struct kdbus_cmd_info { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to EINVAL. @@ -570,9 +574,9 @@ struct kdbus_info { 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. + struct kdbus_cmd_info, items of types + KDBUS_ITEM_OWNED_NAME and + KDBUS_ITEM_CONN_DESCRIPTION may follow here. @@ -580,7 +584,7 @@ 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 + employ the KDBUS_CMD_FREE command for the offset, in order to free the buffer part. See kdbus.pool7 for futher information. @@ -590,17 +594,17 @@ struct kdbus_info { 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. + 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, + filled with an object of type struct kdbus_info, pointed to by the ioctl's offset field. @@ -641,7 +645,7 @@ struct kdbus_info { Metadata information is stored in items here. The item list - contains a KDBUS_ITEM_MAKE_NAME item that + contains a KDBUS_ITEM_MAKE_NAME item that indicates the bus name of the calling connection. @@ -650,7 +654,7 @@ 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 + employ the KDBUS_CMD_FREE command for the offset, in order to free the buffer part. See kdbus.pool7 for futher information. @@ -661,7 +665,7 @@ struct kdbus_info { Updating connection details Some of a connection's details can be updated with the - KDBUS_CMD_CONN_UPDATE ioctl, using the file + KDBUS_CMD_CONN_UPDATE ioctl, using the file descriptor that was used to create the connection. The update command uses the following struct. @@ -714,7 +718,7 @@ struct kdbus_cmd_update { - KDBUS_ITEM_ATTACH_FLAGS_SEND + KDBUS_ITEM_ATTACH_FLAGS_SEND Supply a new set of items that this connection permits to be @@ -724,7 +728,7 @@ struct kdbus_cmd_update { - KDBUS_ITEM_ATTACH_FLAGS_RECV + KDBUS_ITEM_ATTACH_FLAGS_RECV Supply a new set of items to be attached to each message. @@ -733,13 +737,13 @@ struct kdbus_cmd_update { - KDBUS_ITEM_NAME - KDBUS_ITEM_POLICY_ACCESS + 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. + EOPNOTSUPP is returned in errno. @@ -747,7 +751,7 @@ struct kdbus_cmd_update { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to EINVAL. @@ -758,7 +762,7 @@ struct kdbus_cmd_update { Monitor connections ('eavesdropper') Eavesdropping connections are created by setting the - KDBUS_HELLO_MONITOR flag in + KDBUS_HELLO_MONITOR flag in struct kdbus_hello.flags. Such connections have all properties of any other, regular connection, except for the following details: @@ -781,7 +785,7 @@ struct kdbus_cmd_update { Their creation and destruction will not cause - KDBUS_ITEM_ID_{ADD,REMOVE} notifications to be + KDBUS_ITEM_ID_{ADD,REMOVE} notifications to be generated, so other connections cannot detect the presence of an eavesdropper. @@ -799,9 +803,10 @@ struct kdbus_cmd_update { An alternative way of closing down a connection is via the - KDBUS_CMD_BYEBYE ioctl. This ioctl will succeed only + 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 + 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 race-free, without losing any messages. diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml index 17268f8..78caf38 100644 --- a/doc/kdbus.endpoint.xml +++ b/doc/kdbus.endpoint.xml @@ -67,14 +67,14 @@ Creating custom endpoints - To create a new endpoint, the KDBUS_CMD_ENDPOINT_MAKE - command is used. Along with the endpoint's name, which will be used to - expose the endpoint in the + 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, the command also optionally takes items to set up the endpoint's kdbus.policy7. - KDBUS_CMD_ENDPOINT_MAKE takes a - struct kdbus_cmd_make argument. + KDBUS_CMD_ENDPOINT_MAKE takes a + struct kdbus_cmd_make argument. struct kdbus_cmd_make { @@ -101,14 +101,14 @@ struct kdbus_cmd_make { The flags for creation. - KDBUS_MAKE_ACCESS_GROUP + KDBUS_MAKE_ACCESS_GROUP Make the endpoint file group-accessible - KDBUS_MAKE_ACCESS_WORLD + KDBUS_MAKE_ACCESS_WORLD Make the endpoint file world-accessible @@ -137,19 +137,19 @@ struct kdbus_cmd_make { The following items are expected for - KDBUS_CMD_ENDPOINT_MAKE. + KDBUS_CMD_ENDPOINT_MAKE. - KDBUS_ITEM_MAKE_NAME + KDBUS_ITEM_MAKE_NAME Contains a string to identify the endpoint name. - KDBUS_ITEM_NAME - KDBUS_ITEM_POLICY_ACCESS + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS These items are used to set the policy attached to the @@ -161,7 +161,7 @@ struct kdbus_cmd_make { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to EINVAL. @@ -172,13 +172,13 @@ struct kdbus_cmd_make { Updating endpoints To update an existing endpoint, the - KDBUS_CMD_ENDPOINT_UPDATE command is used on the file + KDBUS_CMD_ENDPOINT_UPDATE command is used on the file descriptor that was used to create the update, using - KDBUS_CMD_ENDPOINT_MAKE. The only relevant detail of + KDBUS_CMD_ENDPOINT_MAKE. The only relevant detail of the endpoint that can be updated is the policy. When the command is employed, the policy of the endpoint is replaced atomically with the new set of rules. - The command takes a struct kdbus_cmd_update argument. + The command takes a struct kdbus_cmd_update argument. struct kdbus_cmd_make { @@ -227,12 +227,12 @@ struct kdbus_cmd_make { The following items are expected for - KDBUS_CMD_ENDPOINT_UPDATE. + KDBUS_CMD_ENDPOINT_UPDATE. - KDBUS_ITEM_NAME - KDBUS_ITEM_POLICY_ACCESS + KDBUS_ITEM_NAME + KDBUS_ITEM_POLICY_ACCESS These items are used to set the policy attached to the diff --git a/doc/kdbus.fs.xml b/doc/kdbus.fs.xml index fc2d900..2b7d6cc 100644 --- a/doc/kdbus.fs.xml +++ b/doc/kdbus.fs.xml @@ -31,19 +31,19 @@ The system-wide default mount point for kdbusfs is - /sys/fs/kdbus. + /sys/fs/kdbus. Buses are represented as directories in the file system layout, whereas endpoints are exposed as files inside these directories. On the top-level, a control node is present, which can be opened to - create new buses via the KDBUS_CMD_BUS_MAKE ioctl. + create new buses via the KDBUS_CMD_BUS_MAKE ioctl. Each bus shows a default endpoint called bus, which can be opened to either create a connection - with the KDBUS_CMD_HELLO ioctl, or to create new + with the KDBUS_CMD_HELLO ioctl, or to create new custom endpoints for the bus with - KDBUS_CMD_ENDPOINT_MAKE. + KDBUS_CMD_ENDPOINT_MAKE. See kdbus.bus7, kdbus.connection7 and diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml index 917bf36..a18f40a 100644 --- a/doc/kdbus.item.xml +++ b/doc/kdbus.item.xml @@ -39,11 +39,11 @@ 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 attached to will cause the ioctl to fail - -EINVAL. + 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. 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,8 +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 -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. @@ -97,7 +98,7 @@ Item layout - A struct kdbus_item consists of a + 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. @@ -135,7 +136,7 @@ struct kdbus_item { - struct kdbus_item should never be used to allocate + 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 @@ -186,11 +187,11 @@ struct kdbus_vec { KDBUS_ITEM_PAYLOAD_MEMFD Transports a file descriptor of a memfd in - struct kdbus_memfd in - item.memfd. The size field - has to match the actual size of 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 + struct kdbus_memfd in item.memfd. + The size field has to match the actual size of + 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 for more information on passing of payload data along with a message. @@ -213,7 +214,7 @@ struct kdbus_memfd { the values of this array with valid file descriptor numbers. When received as item attached to a message, the array will contain the numbers of the installed file descriptors, or - -1 in case an error occured. + -1 in case an error occured. filedescriptor. In either case, the number of entries in the array is derived from the item's total size. See @@ -305,7 +306,7 @@ struct kdbus_bloom_filter { KDBUS_ITEM_ID Transports a connection's numerical ID of - a connection as u64 value in + a connection as u64 value in item.id. @@ -315,7 +316,7 @@ struct kdbus_bloom_filter { Transports a name associated with the name registry as null-terminated string as - struct kdbus_name in + struct kdbus_name in item.name. The flags contains the flags of the name. See kdbus.name7 @@ -341,7 +342,7 @@ struct kdbus_name { Contains both the monotonic and the realtime timestamp, taken when the message was processed on the kernel side. - Stored as struct kdbus_timestamp in + Stored as struct kdbus_timestamp in item.timestamp. struct kdbus_timestamp { @@ -359,7 +360,7 @@ struct kdbus_timestamp { Contains credentials such as the user and group in the usual four flavors: real, effective, saved and file-system related. - Stored as struct kdbus_creds in + Stored as struct kdbus_creds in item.creds. struct kdbus_creds { @@ -381,7 +382,7 @@ struct kdbus_creds { Contains the PID, TID and parent PID (PPID) of a remote peer. - Stored as struct kdbus_pids in + Stored as struct kdbus_pids in item.pids. struct kdbus_pids { @@ -398,10 +399,10 @@ struct kdbus_pids { Contains the auxiliary (supplementary) groups a remote peer is a member of, stored as array of - u32 values in item.data32. + u32 values in item.data32. The array length can be determined by looking at the item's total size, substracting the size of the header and and dividing the - remainder by sizeof(u32). + remainder by sizeof(u32). @@ -476,9 +477,9 @@ struct kdbus_pids { KDBUS_ITEM_CAPS Contains sets of capabilities, stored as - struct kdbus_caps in - item.caps. As the item size may increas in the - future, userspace should be written in a way that it takes + struct kdbus_caps in item.caps. + As the item size may increas in the future, userspace should be + written in a way that it takes item.caps.last_cap into account, and derive the number of sets and rows from the item size and the reported number of valid capability bits. @@ -505,7 +506,7 @@ struct kdbus_caps { Contains the audit sessionid and loginuid of a task, stored as - struct kdbus_audit in + struct kdbus_audit in item.audit. struct kdbus_audit { @@ -520,8 +521,8 @@ struct kdbus_audit { KDBUS_ITEM_CONN_DESCRIPTION Contains the connection description, as set - by KDBUS_CMD_HELLO or - KDBUS_CMD_CONN_UPDATE, stored as + by KDBUS_CMD_HELLO or + KDBUS_CMD_CONN_UPDATE, stored as null-terminated string in item.str. Its length can also be derived from the item's total size. diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml index 2201661..cc4c160 100644 --- a/doc/kdbus.match.xml +++ b/doc/kdbus.match.xml @@ -31,12 +31,12 @@ Matches for broadcast messages from other connections A message addressed at the connection ID - KDBUS_DST_ID_BROADCAST (~0ULL) is a broadcast message, - delivered to all connected peers which installed a rule to match certain - properties of the message. Without any rules installed in 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_DST_ID_BROADCAST (~0ULL) is a broadcast + message, delivered to all connected peers which installed a rule to + match certain properties of the message. Without any rules installed in + 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 for more details on implicit policies. @@ -88,8 +88,8 @@ Matches for kernel notifications - To add a match, the KDBUS_CMD_MATCH_ADD ioctl is used, - which takes a struct of the struct described below. + 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 @@ -135,7 +135,7 @@ struct kdbus_cmd_match { Flags to control the behavior of the ioctl. - KDBUS_MATCH_REPLACE + KDBUS_MATCH_REPLACE Make the endpoint file group-accessible @@ -168,7 +168,7 @@ struct kdbus_cmd_match { - KDBUS_ITEM_BLOOM_MASK + KDBUS_ITEM_BLOOM_MASK An item that carries the bloom filter mask to match against @@ -180,7 +180,7 @@ struct kdbus_cmd_match { - KDBUS_ITEM_NAME + KDBUS_ITEM_NAME Specify a name that a sending connection must own at the @@ -191,7 +191,7 @@ struct kdbus_cmd_match { - KDBUS_ITEM_ID + KDBUS_ITEM_ID Specify a sender connection's ID that will match this rule. @@ -200,9 +200,9 @@ struct kdbus_cmd_match { - KDBUS_ITEM_NAME_ADD - KDBUS_ITEM_NAME_REMOVE - KDBUS_ITEM_NAME_CHANGE + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE These items request delivery of broadcast messages that @@ -211,23 +211,23 @@ struct kdbus_cmd_match { kdbus_notify_name_change member. All information specified must be matched in order to make the message pass. Use - KDBUS_MATCH_ID_ANY to + KDBUS_MATCH_ID_ANY to match against any unique connection ID. - KDBUS_ITEM_ID_ADD - KDBUS_ITEM_ID_REMOVE + KDBUS_ITEM_ID_ADD + KDBUS_ITEM_ID_REMOVE These items request delivery of kernel notofications that are generated when a connection is created or terminated. - struct kdbus_notify_id_changeis used to + struct kdbus_notify_id_changeis used to store the actual match information. This item can be used to monitor one particular connection ID, or, when the ID field is set to - KDBUS_MATCH_ID_ANY, all of them. + KDBUS_MATCH_ID_ANY, all of them. @@ -236,7 +236,7 @@ struct kdbus_cmd_match { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + errno set to -EINVAL. @@ -252,11 +252,11 @@ struct kdbus_cmd_match { Removing a match - Matches can be removed through the - KDBUS_CMD_MATCH_REMOVE ioctl, which takes - struct kdbus_cmd_match as argument, but its fields + Matches can be removed with the + KDBUS_CMD_MATCH_REMOVE ioctl, which takes + struct kdbus_cmd_match as argument, but its fields usage slightly differs compared to that of - KDBUS_CMD_MATCH_ADD. + KDBUS_CMD_MATCH_ADD. @@ -349,9 +349,9 @@ struct kdbus_cmd_match { Masks are entities that are always passed to the kernel as part of a - match (with an item of type KDBUS_ITEM_BLOOM_MASK), + match (with an item of type KDBUS_ITEM_BLOOM_MASK), and filters can be attached to signals, with an item of type - KDBUS_ITEM_BLOOM_FILTER. For a filter to match, all + KDBUS_ITEM_BLOOM_FILTER. For a filter to match, all its bits have to be set in the match mask as well. @@ -374,7 +374,7 @@ struct kdbus_cmd_match { Hence, in order to catch all messages, a mask filled with - 0xff bytes can be installed as a wildcard match rule. + 0xff bytes can be installed as a wildcard match rule. diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index 51e7693..61b3355 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -33,7 +33,7 @@ The KDBUS_CMD_SEND ioctl uses a - struct kdbus_cmd_send to describe the message + struct kdbus_cmd_send to describe the message transfer. @@ -106,7 +106,7 @@ struct kdbus_cmd_send { msg_address In this field, userspace has to provide a pointer to a message - (struct kdbus_msg) to send. See below for a + (struct kdbus_msg) to send. See below for a detailed description. @@ -115,7 +115,7 @@ struct kdbus_cmd_send { reply Only used for synchronous replies. See description of - struct kdbus_cmd_recv for more details. + struct kdbus_cmd_recv for more details. @@ -127,7 +127,7 @@ struct kdbus_cmd_send { - KDBUS_ITEM_CANCEL_FD + KDBUS_ITEM_CANCEL_FD When this optional item is passed in, and the call is @@ -137,8 +137,10 @@ struct kdbus_cmd_send { poll2 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 on which + call will return -1 and + errno will be set to + ECANCELED. Any type of file descriptor + on which poll2 can be called on can be used as payload to this item. For asynchronous message sending, this item is allowed but @@ -485,7 +487,7 @@ struct kdbus_msg { With the KDBUS_CMD_RECV ioctl, a - struct kdbus_cmd_recv is used. + struct kdbus_cmd_recv is used. @@ -609,9 +611,9 @@ struct kdbus_cmd_recv { - Both struct kdbus_cmd_recv and - struct kdbus_cmd_send embed - struct kdbus_msg_info. + 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. @@ -644,7 +646,7 @@ struct kdbus_msg_info { 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. + 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 @@ -683,7 +685,7 @@ struct kdbus_msg_info { 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 + pool. The message is stored as struct kdbus_msg at this offset, and can be interpreted with the semantics described above. diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml index 6798e4b..816b337 100644 --- a/doc/kdbus.names.xml +++ b/doc/kdbus.names.xml @@ -27,7 +27,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 - KDBUS_DST_ID_NAME, or when a registry dump is + KDBUS_DST_ID_NAME, or when a registry dump is requested. @@ -73,7 +73,7 @@ Acquiring a name To acquire a name, a client uses the - KDBUS_CMD_NAME_ACQUIRE ioctl with the following data + KDBUS_CMD_NAME_ACQUIRE ioctl with the following data structure. @@ -102,12 +102,12 @@ struct kdbus_cmd_name { Flags to control details in the name acquisition. - KDBUS_NAME_REPLACE_EXISTING + 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) + 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). @@ -116,7 +116,7 @@ struct kdbus_cmd_name { - KDBUS_NAME_ALLOW_REPLACEMENT + KDBUS_NAME_ALLOW_REPLACEMENT Allow other connections to take over this name. When this @@ -127,16 +127,16 @@ struct kdbus_cmd_name { - KDBUS_NAME_QUEUE + 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. + 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. @@ -164,12 +164,12 @@ struct kdbus_cmd_name { Items to submit the name. Currently, one item of type - KDBUS_ITEM_NAME is expected and allowed, and + 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. + errno set to >EINVAL. @@ -180,7 +180,7 @@ struct kdbus_cmd_name { Releasing a name A connection may release a name explicitly with the - KDBUS_CMD_NAME_RELEASE ioctl. If the connection was + 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 @@ -190,8 +190,8 @@ struct kdbus_cmd_name { for more information on connections. - The KDBUS_CMD_NAME_RELEASE ioctl uses the same data - structure as the acquisition call (KDBUS_CMD_NAME_ACQUIRE), + 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. @@ -253,12 +253,12 @@ struct kdbus_cmd_name { Items to submit the name. Currently, one item of type - KDBUS_ITEM_NAME is expected and allowed, and + 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. + errno set to -EINVAL. @@ -269,8 +269,8 @@ struct kdbus_cmd_name { 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. + bus names with the KDBUS_CMD_NAME_LIST ioctl, which + takes a struct kdbus_cmd_name_list as argument. @@ -293,7 +293,7 @@ struct kdbus_cmd_name_list { - KDBUS_NAME_LIST_UNIQUE + KDBUS_NAME_LIST_UNIQUE List the unique (numeric) IDs of the connection, whether it @@ -303,7 +303,7 @@ struct kdbus_cmd_name_list { - KDBUS_NAME_LIST_NAMES + KDBUS_NAME_LIST_NAMES List well-known names stored in the database which are @@ -313,7 +313,7 @@ struct kdbus_cmd_name_list { - KDBUS_NAME_LIST_ACTIVATORS + KDBUS_NAME_LIST_ACTIVATORS List names that are owned by an activator. @@ -322,7 +322,7 @@ struct kdbus_cmd_name_list { - KDBUS_NAME_LIST_QUEUED + KDBUS_NAME_LIST_QUEUED List connections that are not yet owning a name but are @@ -360,11 +360,11 @@ struct kdbus_cmd_name_list { The returned list of names is stored in a - struct kdbus_name_list that in turn + struct kdbus_name_list that in turn contains a dynamic number of - struct kdbus_cmd_name that carry the actual + struct kdbus_cmd_name that carry the actual information. The fields inside that - struct kdbus_cmd_name is described next. + struct kdbus_cmd_name is described next. @@ -405,13 +405,13 @@ struct kdbus_name_info { Items containing the actual name. Currently, one item of type - KDBUS_ITEM_OWNED_NAME will be attached, + 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 + KDBUS_NAME_ALLOW_REPLACEMENT Other connections are allowed to take over this name from the @@ -421,7 +421,7 @@ struct kdbus_name_info { - KDBUS_NAME_IN_QUEUE + KDBUS_NAME_IN_QUEUE When retrieving a list of currently acquired names in the @@ -433,7 +433,7 @@ struct kdbus_name_info { - KDBUS_NAME_ACTIVATOR + KDBUS_NAME_ACTIVATOR An activator connection owns a name as a placeholder for an @@ -444,7 +444,7 @@ struct kdbus_name_info { . - In contrast to KDBUS_NAME_REPLACE_EXISTING, + 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 @@ -452,9 +452,9 @@ struct kdbus_name_info { 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 + 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. diff --git a/doc/kdbus.policy.xml b/doc/kdbus.policy.xml index 0e9f14e..bd7ad45 100644 --- a/doc/kdbus.policy.xml +++ b/doc/kdbus.policy.xml @@ -32,7 +32,7 @@ - KDBUS_CMD_HELLO + KDBUS_CMD_HELLO When creating, or updating, a policy holder connection. See kdbus.connection7. @@ -40,8 +40,8 @@ - KDBUS_CMD_ENDPOINT_MAKE - KDBUS_CMD_ENDPOINT_UPDATE + KDBUS_CMD_ENDPOINT_MAKE + KDBUS_CMD_ENDPOINT_UPDATE When creating, or updating, a bus custom endpoint. See kdbus.endpoint7. @@ -51,24 +51,24 @@ In all cases, the name and policy access information is stored in items - of type KDBUS_ITEM_NAME and - KDBUS_ITEM_POLICY_ACCESS. For this transport, the + of type KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS. For this transport, the following rules apply. - An item of type KDBUS_ITEM_NAME must be followed - by at least one KDBUS_ITEM_POLICY_ACCESS item. + An item of type KDBUS_ITEM_NAME must be followed + by at least one KDBUS_ITEM_POLICY_ACCESS item. - An item of type KDBUS_ITEM_NAME can be followed - by an arbitrary number of KDBUS_ITEM_POLICY_ACCESS - items. + An item of type KDBUS_ITEM_NAME can be followed + by an arbitrary number of + KDBUS_ITEM_POLICY_ACCESS items. @@ -80,14 +80,14 @@ - Names passed in items of type KDBUS_ITEM_NAME must + Names passed in items of type KDBUS_ITEM_NAME must comply to the rules of valid kdbus names. See kdbus.names7 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 + 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. @@ -111,7 +111,7 @@ struct kdbus_policy_access { - KDBUS_POLICY_ACCESS_USER + KDBUS_POLICY_ACCESS_USER Grant access to a user with the UID stored in the id field. @@ -119,7 +119,7 @@ struct kdbus_policy_access { - KDBUS_POLICY_ACCESS_GROUP + KDBUS_POLICY_ACCESS_GROUP Grant access to a user with the GID stored in the id field. @@ -127,7 +127,7 @@ struct kdbus_policy_access { - KDBUS_POLICY_ACCESS_WORLD + KDBUS_POLICY_ACCESS_WORLD Grant access to everyone. The id field is ignored. @@ -146,21 +146,21 @@ struct kdbus_policy_access { - KDBUS_POLICY_SEE + KDBUS_POLICY_SEE Allow the name to be seen. - KDBUS_POLICY_TALK + KDBUS_POLICY_TALK Allow the name to be talked to. - KDBUS_POLICY_OWN + KDBUS_POLICY_OWN Allow the name to be owned. @@ -172,8 +172,8 @@ struct kdbus_policy_access { id - For KDBUS_POLICY_ACCESS_USER, stores the UID. - For KDBUS_POLICY_ACCESS_GROUP, stores the GID. + For KDBUS_POLICY_ACCESS_USER, stores the UID. + For KDBUS_POLICY_ACCESS_GROUP, stores the GID. @@ -190,12 +190,15 @@ struct kdbus_policy_access { Wildcard names - Policy holder connections may upload names that contain the wildcard suffix - (".*"). Such a policy entry is effective for every - well-known name that extends the provided name by exactly one more level. + Policy holder connections may upload names that contain the wildcard + suffix (".*"). Such a policy entry is effective for + every well-known name that extends the provided name by exactly one more + level. - For example, the name "foo.bar.*" matches both "foo.bar.baz" and - "foo.bar.bazbaz" are, but not "foo.bar.baz.baz". + For example, the name "foo.bar.*" matches both + "foo.bar.baz" and + "foo.bar.bazbaz" are, but not + "foo.bar.baz.baz". This allows connections to take control over multiple names that the policy holder doesn't need to know about when uploading the policy. @@ -259,8 +262,8 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK 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 - -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 @@ -311,7 +314,7 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK - Policy rules are always enforced for TALK access, + Policy rules are always enforced for TALK access, even if both ends are running under the same user. This includes broadcast messages. @@ -319,7 +322,7 @@ KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK To restrict the set of names that can be seen, endpoint policies can - install SEE policies. + install SEE policies. diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index fb0b468..db9d3c3 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -25,8 +25,8 @@ 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. Internally, the pool is segmented + KDBUS_ITEM_BLOOM_PARAMETER item that is returned by + KDBUS_CMD_HELLO. Internally, the pool is segmented into slices, each referenced by its offset in the pool. @@ -37,25 +37,25 @@ - KDBUS_CMD_HELLO + KDBUS_CMD_HELLO ... to receive details about the bus the connection was made to - KDBUS_CMD_RECV + KDBUS_CMD_RECV ... to receive a message - KDBUS_CMD_NAME_LIST + KDBUS_CMD_NAME_LIST ... to dump the name registry - KDBUS_CMD_CONN_INFO + KDBUS_CMD_CONN_INFO ... to retrieve information on a connection @@ -67,7 +67,7 @@ The offset fields 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 that offset + KDBUS_CMD_FREE has to be called on that offset (see below). Otherwise, the pool will fill up, and the connection won't be able to receive any more information through its pool. @@ -94,7 +94,7 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); The file descriptor used to map the memory must be the one that was used to create the connection In other words, the one that was used to call - KDBUS_CMD_HELLO. See + KDBUS_CMD_HELLO. See kdbus.connection7 for more details. @@ -133,11 +133,11 @@ buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0); Freeing pool slices - The KDBUS_CMD_FREE ioctl is used to free a slice + The KDBUS_CMD_FREE ioctl is used to free a slice inside the pool, describing an offset that was returned in an offset field of another ioctl struct. - The KDBUS_CMD_FREE command takes a - struct kdbus_cmd_free as argument: + The KDBUS_CMD_FREE command takes a + struct kdbus_cmd_free as argument. diff --git a/doc/kdbus.xml b/doc/kdbus.xml index d86609e..b769824 100644 --- a/doc/kdbus.xml +++ b/doc/kdbus.xml @@ -114,11 +114,11 @@ 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 + bus and becoming an active client with the + KDBUS_CMD_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. @@ -363,22 +363,22 @@ - When a bus is created (KDBUS_CMD_MAKE), information + 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. + kernel via the KDBUS_CMD_BUS_CREATOR_INFO call. - When a connection is created (KDBUS_CMD_HELLO), + 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). + (KDBUS_CMD_CONN_INFO). - When a message is sent (KDBUS_CMD_SEND), information + 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 @@ -436,7 +436,7 @@ - [2] When connecting to a bus (KDBUS_CMD_HELLO), and + [2] When connecting to a bus (KDBUS_CMD_HELLO), and (~b & d) != 0, the call will fail, the connection is refused. @@ -471,114 +471,114 @@ - KDBUS_ATTACH_TIMESTAMP + KDBUS_ATTACH_TIMESTAMP Requests the attachment of an item of type - KDBUS_ITEM_TIMESTAMP. + KDBUS_ITEM_TIMESTAMP. - KDBUS_ATTACH_CREDS + KDBUS_ATTACH_CREDS Requests the attachment of an item of type - KDBUS_ITEM_CREDS. + KDBUS_ITEM_CREDS. - KDBUS_ATTACH_PIDS + KDBUS_ATTACH_PIDS Requests the attachment of an item of type - KDBUS_ITEM_PIDS. + KDBUS_ITEM_PIDS. - KDBUS_ATTACH_AUXGROUPS + KDBUS_ATTACH_AUXGROUPS Requests the attachment of an item of type - KDBUS_ITEM_AUXGROUPS. + KDBUS_ITEM_AUXGROUPS. - KDBUS_ATTACH_NAMES + KDBUS_ATTACH_NAMES Requests the attachment of an item of type - KDBUS_ITEM_OWNED_NAME. + KDBUS_ITEM_OWNED_NAME. - KDBUS_ATTACH_TID_COMM + KDBUS_ATTACH_TID_COMM Requests the attachment of an item of type - KDBUS_ITEM_TID_COMM. + KDBUS_ITEM_TID_COMM. - KDBUS_ATTACH_PID_COMM + KDBUS_ATTACH_PID_COMM Requests the attachment of an item of type - KDBUS_ITEM_PID_COMM. + KDBUS_ITEM_PID_COMM. - KDBUS_ATTACH_EXE + KDBUS_ATTACH_EXE Requests the attachment of an item of type - KDBUS_ITEM_EXE. + KDBUS_ITEM_EXE. - KDBUS_ATTACH_CMDLINE + KDBUS_ATTACH_CMDLINE Requests the attachment of an item of type - KDBUS_ITEM_CMDLINE. + KDBUS_ITEM_CMDLINE. - KDBUS_ATTACH_CGROUP + KDBUS_ATTACH_CGROUP Requests the attachment of an item of type - KDBUS_ITEM_CGROUP. + KDBUS_ITEM_CGROUP. - KDBUS_ATTACH_CAPS + KDBUS_ATTACH_CAPS Requests the attachment of an item of type - KDBUS_ITEM_CAPS. + KDBUS_ITEM_CAPS. - KDBUS_ATTACH_SECLABEL + KDBUS_ATTACH_SECLABEL Requests the attachment of an item of type - KDBUS_ITEM_SECLABEL. + KDBUS_ITEM_SECLABEL. - KDBUS_ATTACH_AUDIT + KDBUS_ATTACH_AUDIT Requests the attachment of an item of type - KDBUS_ITEM_AUDIT. + KDBUS_ITEM_AUDIT. - KDBUS_ATTACH_CONN_DESCRIPTION + KDBUS_ATTACH_CONN_DESCRIPTION Requests the attachment of an item of type - KDBUS_ITEM_CONN_DESCRIPTION. + KDBUS_ITEM_CONN_DESCRIPTION. -- 2.34.1