From 8442b8613d878e9c64b39c52dbe5ec59cb2a2962 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Wed, 28 Jan 2015 12:34:06 +0100 Subject: [PATCH] doc: turn some into Signed-off-by: Daniel Mack --- doc/kdbus.bus.xml | 14 +- doc/kdbus.connection.xml | 56 ++++---- doc/kdbus.endpoint.xml | 32 ++--- doc/kdbus.item.xml | 92 +++++++------- doc/kdbus.match.xml | 14 +- doc/kdbus.message.xml | 268 ++++++++++++++++++++------------------- doc/kdbus.names.xml | 26 ++-- doc/kdbus.pool.xml | 13 +- 8 files changed, 263 insertions(+), 252 deletions(-) diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml index 5698331..8b1412c 100644 --- a/doc/kdbus.bus.xml +++ b/doc/kdbus.bus.xml @@ -211,41 +211,41 @@ struct kdbus_cmd_make { - <varname>KDBUS_CMD_BUS_MAKE</varname> may fail with the following errors + <constant>KDBUS_CMD_BUS_MAKE</constant> may fail with the following errors - EBADMSG + EBADMSG A mandatory item is missing. - EINVAL + EINVAL - The flags supplied in the struct kdbus_cmd_make + The flags supplied in the struct kdbus_cmd_make are invalid or the supplied name does not start with the current UID and a '-'. - EEXIST + EEXIST A bus of that name already exists. - ESHUTDOWN + ESHUTDOWN The kdbus mount instance for the bus was already shut down. - EMFILE + EMFILE The maximum number of buses for the current user is exhausted. diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml index 7ba4163..1804df9 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -816,43 +816,43 @@ struct kdbus_cmd_update { - <varname>KDBUS_CMD_HELLO</varname> may fail with the following errors + <constant>KDBUS_CMD_HELLO</constant> may fail with the following errors - EFAULT + EFAULT The supplied pool size was 0 or not a multiple of the page size. - EINVAL + EINVAL - The flags supplied in struct kdbus_cmd_make are + The flags supplied in struct kdbus_cmd_make are invalid. - EINVAL + EINVAL An illegal combination of - KDBUS_HELLO_MONITOR, - KDBUS_HELLO_ACTIVATOR and - KDBUS_HELLO_POLICY_HOLDER was passed in the flags. + KDBUS_HELLO_MONITOR, + KDBUS_HELLO_ACTIVATOR and + KDBUS_HELLO_POLICY_HOLDER was passed in the flags. - EINVAL + EINVAL An invalid set of items was supplied. - ECONNREFUSED + ECONNREFUSED The attach_flags_send field did not satisfy the requirements of the bus. @@ -860,50 +860,50 @@ struct kdbus_cmd_update { - EPERM + EPERM - A KDBUS_ITEM_CREDS items was supplied, but the + A KDBUS_ITEM_CREDS items was supplied, but the current user is not privileged. - ESHUTDOWN + ESHUTDOWN The bus you were trying to connect to has already been shut down. - EMFILE + EMFILE The maximum number of connections on the bus has been reached. - EOPNOTSUPP + EOPNOTSUPP The endpoint does not support the connection flags supplied in - struct kdbus_cmd_hello. + struct kdbus_cmd_hello. - <varname>KDBUS_CMD_BYEBYE</varname> may fail with the following errors + <constant>KDBUS_CMD_BYEBYE</constant> may fail with the following errors - EALREADY + EALREADY The connection has already been shut down. - EBUSY + EBUSY There are still messages queued up in the connection's pool. @@ -912,11 +912,11 @@ struct kdbus_cmd_update { - <varname>KDBUS_CMD_CONN_INFO</varname> may fail with the following errors + <constant>KDBUS_CMD_CONN_INFO</constant> may fail with the following errors - EINVAL + EINVAL Invalid flags, or neither an ID nor a name was provided, or the name is invalid. @@ -924,14 +924,14 @@ struct kdbus_cmd_update { - ESRCH + ESRCH Connection lookup by name failed. - ENXIO + ENXIO No connection with the provided connection ID found. @@ -940,18 +940,18 @@ struct kdbus_cmd_update { - <varname>KDBUS_CMD_CONN_UPDATE</varname> may fail with the following errors + <constant>KDBUS_CMD_CONN_UPDATE</constant> may fail with the following errors - EINVAL + EINVAL Illegal flags or items. - EINVAL + EINVAL Wildcards submitted in policy entries, or illegal sequence of policy items. @@ -959,14 +959,14 @@ struct kdbus_cmd_update { - EOPNOTSUPP + EOPNOTSUPP Operation not supported by connection. - E2BIG + E2BIG Too many policy items attached. diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml index 2afa016..17268f8 100644 --- a/doc/kdbus.endpoint.xml +++ b/doc/kdbus.endpoint.xml @@ -246,7 +246,7 @@ struct kdbus_cmd_make { Unrecognized items are rejected, and the ioctl will fail with - -EINVAL. + -EINVAL. @@ -261,34 +261,34 @@ struct kdbus_cmd_make { - <varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may fail with the following errors + <constant>KDBUS_CMD_ENDPOINT_MAKE</constant> may fail with the following errors - EINVAL + EINVAL - The flags supplied in the struct kdbus_cmd_make + The flags supplied in the struct kdbus_cmd_make are invalid. - EINVAL + EINVAL - Illegal combination of KDBUS_ITEM_NAME and - KDBUS_ITEM_POLICY_ACCESS was provided. + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. - EEXIST + EEXIST An endpoint of that name already exists. - EPERM + EPERM The calling user is not privileged. See kdbus7 @@ -299,27 +299,27 @@ struct kdbus_cmd_make { - <varname>KDBUS_CMD_ENDPOINT_UPDATE</varname> may fail with the following errors + <constant>KDBUS_CMD_ENDPOINT_UPDATE</constant> may fail with the following errors - EINVAL + EINVAL - The flags supplied in the struct kdbus_cmd_update + The flags supplied in the struct kdbus_cmd_update are invalid. - EINVAL + EINVAL - Illegal combination of KDBUS_ITEM_NAME and - KDBUS_ITEM_POLICY_ACCESS was provided. + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. - EEXIST + EEXIST An endpoint of that name already exists. diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml index 9faece2..917bf36 100644 --- a/doc/kdbus.item.xml +++ b/doc/kdbus.item.xml @@ -150,19 +150,19 @@ struct kdbus_item { Command specific items - KDBUS_ITEM_PAYLOAD_VEC - KDBUS_ITEM_PAYLOAD_OFF + KDBUS_ITEM_PAYLOAD_VEC + KDBUS_ITEM_PAYLOAD_OFF Messages are directly copied by the sending process into the receiver's kdbus.pool7. 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 + the data anywhere else. KDBUS_ITEM_PAYLOAD_VEC is used when sending message. The item references a memory address when the payload data can be found. - KDBUS_ITEM_PAYLOAD_OFF is used when messages - are received, and the offset + KDBUS_ITEM_PAYLOAD_OFF is used when messages + are received, and the offset value describes the offset inside the receiving connection's kdbus.pool7 where the message payload can be found. @@ -183,7 +183,7 @@ struct kdbus_vec { - KDBUS_ITEM_PAYLOAD_MEMFD + KDBUS_ITEM_PAYLOAD_MEMFD Transports a file descriptor of a memfd in struct kdbus_memfd in @@ -206,10 +206,10 @@ struct kdbus_memfd { - KDBUS_ITEM_FDS + KDBUS_ITEM_FDS Contains an array of file descriptors. - When used with KDBUS_CMD_SEND, userspace sets + When used with KDBUS_CMD_SEND, userspace sets 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 @@ -228,10 +228,10 @@ struct kdbus_memfd { Items specific to some commands - KDBUS_ITEM_CANCEL_FD + KDBUS_ITEM_CANCEL_FD Transports a file descriptor that can be used to cancel a - synchronous KDBUS_CMD_SEND operation by + synchronous KDBUS_CMD_SEND operation by writing to it. The file descriptor is stored in item.fd[0]. The item may only contain one filedescriptor. See @@ -241,7 +241,7 @@ struct kdbus_memfd { - KDBUS_ITEM_BLOOM_PARAMETER + KDBUS_ITEM_BLOOM_PARAMETER TODO struct kdbus_bloom_parameter { @@ -253,7 +253,7 @@ struct kdbus_bloom_parameter { - KDBUS_ITEM_BLOOM_FILTER + KDBUS_ITEM_BLOOM_FILTER TODO struct kdbus_bloom_filter { @@ -265,32 +265,32 @@ struct kdbus_bloom_filter { - KDBUS_ITEM_BLOOM_MASK + KDBUS_ITEM_BLOOM_MASK TODO - KDBUS_ITEM_DST_NAME + KDBUS_ITEM_DST_NAME Contains a well-known name to send a message to, as null-terminated string in item.str. This item is used with - KDBUS_CMD_SEND. See + KDBUS_CMD_SEND. See kdbus.message7 for more information on how to send a message. - KDBUS_ITEM_MAKE_NAME + KDBUS_ITEM_MAKE_NAME TODO - KDBUS_ITEM_ATTACH_FLAGS_SEND - KDBUS_ITEM_ATTACH_FLAGS_RECV + KDBUS_ITEM_ATTACH_FLAGS_SEND + KDBUS_ITEM_ATTACH_FLAGS_RECV Contains a set of attach flags at send or receive time. See @@ -302,7 +302,7 @@ struct kdbus_bloom_filter { - KDBUS_ITEM_ID + KDBUS_ITEM_ID Transports a connection's numerical ID of a connection as u64 value in @@ -311,7 +311,7 @@ struct kdbus_bloom_filter { - KDBUS_ITEM_NAME + KDBUS_ITEM_NAME Transports a name associated with the name registry as null-terminated string as @@ -336,7 +336,7 @@ struct kdbus_name { - KDBUS_ITEM_TIMESTAMP + KDBUS_ITEM_TIMESTAMP Contains both the monotonic and the realtime timestamp, taken when the message @@ -354,7 +354,7 @@ struct kdbus_timestamp { - KDBUS_ITEM_CREDS + KDBUS_ITEM_CREDS Contains credentials such as the user and group in the usual four flavors: @@ -377,7 +377,7 @@ struct kdbus_creds { - KDBUS_ITEM_PIDS + KDBUS_ITEM_PIDS Contains the PID, TID and parent PID (PPID) of a remote peer. @@ -394,7 +394,7 @@ struct kdbus_pids { - KDBUS_ITEM_AUXGROUPS + KDBUS_ITEM_AUXGROUPS Contains the auxiliary (supplementary) groups a remote peer is a member of, stored as array of @@ -406,7 +406,7 @@ struct kdbus_pids { - KDBUS_ITEM_OWNED_NAME + KDBUS_ITEM_OWNED_NAME Contains a well-known name currently owned by a connection. The name is stored as null-terminated string in @@ -416,7 +416,7 @@ struct kdbus_pids { - KDBUS_ITEM_TID_COMM [*] + KDBUS_ITEM_TID_COMM [*] Contains the comm of a task's TID, stored as null-terminated string in @@ -428,7 +428,7 @@ struct kdbus_pids { - KDBUS_ITEM_PID_COMM [*] + KDBUS_ITEM_PID_COMM [*] Contains the comm of a task's PID, stored as null-terminated string in @@ -440,7 +440,7 @@ struct kdbus_pids { - KDBUS_ITEM_EXE [*] + KDBUS_ITEM_EXE [*] Contains the path to the executable of a task, stored as null-terminated string in @@ -452,7 +452,7 @@ struct kdbus_pids { - KDBUS_ITEM_CMDLINE [*] + KDBUS_ITEM_CMDLINE [*] Contains the command line arguments of a task, stored as an array of null-terminated @@ -464,7 +464,7 @@ struct kdbus_pids { - KDBUS_ITEM_CGROUP + KDBUS_ITEM_CGROUP Contains the cgroup path of a task, stored as null-terminated string in item.str. Its @@ -473,7 +473,7 @@ struct kdbus_pids { - KDBUS_ITEM_CAPS + KDBUS_ITEM_CAPS Contains sets of capabilities, stored as struct kdbus_caps in @@ -492,7 +492,7 @@ struct kdbus_caps { - KDBUS_ITEM_SECLABEL + KDBUS_ITEM_SECLABEL Contains the LSM label of a task, stored as null-terminated string in item.str. Its length @@ -501,7 +501,7 @@ struct kdbus_caps { - KDBUS_ITEM_AUDIT + KDBUS_ITEM_AUDIT Contains the audit sessionid and loginuid of a task, stored as @@ -517,7 +517,7 @@ struct kdbus_audit { - KDBUS_ITEM_CONN_DESCRIPTION + KDBUS_ITEM_CONN_DESCRIPTION Contains the connection description, as set by KDBUS_CMD_HELLO or @@ -537,10 +537,10 @@ struct kdbus_audit { [*] Note that the content stored in metadata items of type - KDBUS_ITEM_TID_COMM, - KDBUS_ITEM_PID_COMM, - KDBUS_ITEM_EXE and - KDBUS_ITEM_CMDLINE + KDBUS_ITEM_TID_COMM, + KDBUS_ITEM_PID_COMM, + KDBUS_ITEM_EXE and + KDBUS_ITEM_CMDLINE can easily be tampered by the sending tasks. Therefore, they should not be used for any sort of security relevant assumptions. The only reason they are transmitted is to let @@ -555,7 +555,7 @@ struct kdbus_audit { - KDBUS_ITEM_POLICY_ACCESS + KDBUS_ITEM_POLICY_ACCESS This item describes a policy access entry to access the policy database of a @@ -575,9 +575,9 @@ struct kdbus_policy_access { - KDBUS_ITEM_NAME_ADD - KDBUS_ITEM_NAME_REMOVE - KDBUS_ITEM_NAME_CHANGE + KDBUS_ITEM_NAME_ADD + KDBUS_ITEM_NAME_REMOVE + KDBUS_ITEM_NAME_CHANGE TODO struct kdbus_notify_name_change { @@ -590,8 +590,8 @@ struct kdbus_notify_name_change { - KDBUS_ITEM_ID_ADD - KDBUS_ITEM_ID_REMOVE + KDBUS_ITEM_ID_ADD + KDBUS_ITEM_ID_REMOVE TODO struct kdbus_notify_id_change { @@ -603,13 +603,13 @@ struct kdbus_notify_id_change { - KDBUS_ITEM_REPLY_TIMEOUT + KDBUS_ITEM_REPLY_TIMEOUT TODO - KDBUS_ITEM_REPLY_DEAD + KDBUS_ITEM_REPLY_DEAD TODO diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml index ff8d15e..2201661 100644 --- a/doc/kdbus.match.xml +++ b/doc/kdbus.match.xml @@ -402,25 +402,25 @@ struct kdbus_cmd_match { - <varname>KDBUS_CMD_MATCH_ADD</varname> may fail with the following errors + <constant>KDBUS_CMD_MATCH_ADD</constant> may fail with the following errors - EINVAL + EINVAL Illegal flags or items. - EDOM + EDOM Illegal bloom filter size. - EMFILE + EMFILE Too many matches for this connection. @@ -429,18 +429,18 @@ struct kdbus_cmd_match { - <varname>KDBUS_CMD_MATCH_REMOVE</varname> may fail with the following errors + <constant>KDBUS_CMD_MATCH_REMOVE</constant> may fail with the following errors - EINVAL + EINVAL Illegal flags. - EBADSLT + EBADSLT A match entry with the given cookie could not be found. diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index 167cd59..51e7693 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -23,7 +23,7 @@ Description - Messages are passed to the kernel with the KDBUS_CMD_SEND + Messages are passed to the kernel with the KDBUS_CMD_SEND ioctl. Depending on the destination address of the message, the kernel delivers the message to the specific destination connection, or to all connections on the same bus. @@ -32,7 +32,7 @@ - The KDBUS_CMD_SEND ioctl uses a + The KDBUS_CMD_SEND ioctl uses a struct kdbus_cmd_send to describe the message transfer. @@ -64,7 +64,7 @@ struct kdbus_cmd_send { Flags for message delivery - KDBUS_SEND_SYNC_REPLY + KDBUS_SEND_SYNC_REPLY By default, all calls to kdbus are considered asynchronous, @@ -190,35 +190,38 @@ struct kdbus_msg { Flags to describe message details. - KDBUS_MSG_EXPECT_REPLY + KDBUS_MSG_EXPECT_REPLY - Expect a reply to this message from the remote peer. With this bit set, - the timeout_ns field must be set to a non-zero number of nanoseconds in - which the receiving peer is expected to reply. If such a reply is not - received in time, the sender will be notified with a timeout message - (see below). The value must be an absolute value, in nanoseconds and - based on CLOCK_MONOTONIC. + Expect a reply to this message from the remote peer. With + this bit set, the timeout_ns field must be set to a non-zero + number of nanoseconds in which the receiving peer is expected + to reply. If such a reply is not received in time, the sender + will be notified with a timeout message (see below). The + value must be an absolute value, in nanoseconds and based on + CLOCK_MONOTONIC. - For a message to be accepted as reply, it must be a direct message to - the original sender (not a broadcast), and its kdbus_msg.reply_cookie - must match the previous message's kdbus_msg.cookie. + For a message to be accepted as reply, it must be a direct + message to the original sender (not a broadcast), and its + kdbus_msg.reply_cookie must match the + previous message's kdbus_msg.cookie. - Expected replies also temporarily open the policy of the sending - connection, so the other peer is allowed to respond within the given - time window. + Expected replies also temporarily open the policy of the + sending connection, so the other peer is allowed to respond + within the given time window. - KDBUS_MSG_NO_AUTO_START + KDBUS_MSG_NO_AUTO_START - By default, when a message is sent to an activator connection, the - activator is notified and will start an implementer. This flag inhibits - that behavior. With this bit set, and the remote being an activator, - -EADDRNOTAVAIL is returned from the ioctl. + By default, when a message is sent to an activator + connection, the activator is notified and will start an + implementer. This flag inhibits that behavior. With this bit + set, and the remote being an activator, the ioctl will fail + with errno set to EADDRNOTAVAIL. @@ -241,12 +244,12 @@ struct kdbus_msg { dst_id The numeric ID of the destination connection, or - KDBUS_DST_ID_BROADCAST + KDBUS_DST_ID_BROADCAST (~0ULL) to address every peer on the bus, or - KDBUS_DST_ID_NAME (0) to look + KDBUS_DST_ID_NAME (0) to look it up dynamically from the bus' name registry. In the latter case, an item of type - KDBUS_ITEM_DST_NAME is mandatory. + KDBUS_ITEM_DST_NAME is mandatory. @@ -262,10 +265,10 @@ struct kdbus_msg { payload_type Type of the payload in the actual data records. Currently, only - KDBUS_PAYLOAD_DBUS is accepted as input value + KDBUS_PAYLOAD_DBUS is accepted as input value of this field. When receiving messages that are generated by the kernel (notifications), this field will contain - KDBUS_PAYLOAD_KERNEL. + KDBUS_PAYLOAD_KERNEL. @@ -283,7 +286,7 @@ 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_MONOTONIC. Also see clock_gettime2. @@ -305,9 +308,9 @@ struct kdbus_msg { - KDBUS_ITEM_PAYLOAD_VEC - KDBUS_ITEM_PAYLOAD_MEMFD - KDBUS_ITEM_FDS + KDBUS_ITEM_PAYLOAD_VEC + KDBUS_ITEM_PAYLOAD_MEMFD + KDBUS_ITEM_FDS Actual data records containing the payload. See section @@ -317,7 +320,7 @@ struct kdbus_msg { - KDBUS_ITEM_BLOOM_FILTER + KDBUS_ITEM_BLOOM_FILTER Bloom filter for matches (see below). @@ -326,14 +329,15 @@ struct kdbus_msg { - KDBUS_ITEM_DST_NAME + KDBUS_ITEM_DST_NAME Well-known name to send this message to. Required if dst_id is set to - KDBUS_DST_ID_NAME. + KDBUS_DST_ID_NAME. If a connection holding the given name can't be found, - -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, @@ -420,7 +424,7 @@ struct kdbus_msg { - KDBUS_MSG_PAYLOAD_VEC + KDBUS_MSG_PAYLOAD_VEC Messages are directly copied by the sending process into the receiver's pool. @@ -431,7 +435,7 @@ struct kdbus_msg { - KDBUS_MSG_PAYLOAD_MEMFD + KDBUS_MSG_PAYLOAD_MEMFD Messages can reference memfd files which contain the data. @@ -440,7 +444,7 @@ struct kdbus_msg { Only memfds that have - (F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL) + (F_SEAL_SHRINK|F_SEAL_GROW|F_SEAL_WRITE|F_SEAL_SEAL) set are accepted as payload data, which enforces reliable passing of data. The receiver can assume that neither the sender nor anyone else can alter the content after the message is sent. @@ -480,7 +484,8 @@ struct kdbus_msg { - With the KDBUS_CMD_RECV ioctl, a struct kdbus_cmd_recv is used. + With the KDBUS_CMD_RECV ioctl, a + struct kdbus_cmd_recv is used. @@ -511,7 +516,7 @@ struct kdbus_cmd_recv { Flags to control the receive command. - KDBUS_RECV_PEEK + KDBUS_RECV_PEEK Just return the location of the next message. Do not install @@ -522,19 +527,19 @@ struct kdbus_cmd_recv { - KDBUS_RECV_DROP + KDBUS_RECV_DROP Drop the next message without doing anything else with it, and free the pool slice. This a short-cut for - KDBUS_RECV_PEEK and - KDBUS_CMD_FREE. + KDBUS_RECV_PEEK and + KDBUS_CMD_FREE. - KDBUS_RECV_USE_PRIORITY + KDBUS_RECV_USE_PRIORITY Dequeue the messages ordered by their priority, and filtering @@ -564,20 +569,21 @@ struct kdbus_cmd_recv { priority - With KDBUS_RECV_USE_PRIORITY set in + With KDBUS_RECV_USE_PRIORITY set in flags, messages will be dequeued ordered by their priority, starting with the highest value. Also, messages will be filtered by the value given in this field, so the returned message will at least have the requested priority. If no such message is - waiting in the queue, -ENOMSG is returned. + waiting in the queue, the ioctl will fail, and errno will be set to + ENOMSG. dropped_msgs - If the CMD_RECV ioctl fails with - -EOVERFLOW, this field is filled by + 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. @@ -597,7 +603,7 @@ struct kdbus_cmd_recv { Items to specify further details for the receive command. Currently unused, and all items will be rejected with - -EINVAL, + -EINVAL, @@ -606,7 +612,7 @@ struct kdbus_cmd_recv { 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 + For the KDBUS_CMD_SEND ioctl, it is used to catch synchronous replies, if one was requested, and is unused otherwise. @@ -626,7 +632,7 @@ struct kdbus_msg_info { 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_CMD_FREE. See kdbus.pool7 for further details. @@ -635,8 +641,8 @@ struct kdbus_msg_info { msg_size - Upon successful return of the ioctl, this field contains the size of the - allocated slice at offset offset. + Upon successful return of the ioctl, this field contains the size of + the allocated slice at offset offset. It is the combination of the size of the stored struct kdbus_msg object plus all appended VECs. You can use it in combination with offset to map @@ -650,19 +656,21 @@ struct kdbus_msg_info { return_flags - Kernel-provided return flags. Currently, the following flags are defined. + Kernel-provided return flags. Currently, the following flags are + defined. - KDBUS_RECV_RETURN_INCOMPLETE_FDS + KDBUS_RECV_RETURN_INCOMPLETE_FDS - The message contained file descriptors which couldn't be installed - into the receiver's task. Most probably that happened because the - maximum number of file descriptors for that task were exceeded. - The message is still delivered, so this is not a fatal condition. - File descriptors inside the KDBUS_ITEM_FDS - item that could not be installed will be set to -1. + The message contained file descriptors which couldn't be + installed into the receiver's task. Most probably that + happened because the maximum number of file descriptors for + that task were exceeded. The message is still delivered, so + this is not a fatal condition. File descriptors inside the + KDBUS_ITEM_FDS item that could not be + installed will be set to -1. @@ -672,25 +680,25 @@ struct kdbus_msg_info { - Unless KDBUS_RECV_DROP was passed after a successful+ - KDBUS_CMD_RECV ioctl, the offset + Unless KDBUS_RECV_DROP was passed after a successful + KDBUS_CMD_RECV ioctl, the offset field contains the location of the new message inside the receiver's pool. The message is stored as struct kdbus_msg at this offset, and can be interpreted with the semantics described above. Also, if the connection allowed for file descriptor to be passed - (KDBUS_HELLO_ACCEPT_FD), and if the message contained + (KDBUS_HELLO_ACCEPT_FD), and if the message contained any, they will be installed into the receiving process when the - KDBUS_CMD_RECV ioctl is called. + KDBUS_CMD_RECV ioctl is called. The receiving task is obliged to close all of them appropriately. If - KDBUS_RECV_PEEK is set, no file descriptors are + KDBUS_RECV_PEEK is set, no file descriptors are installed. This allows for peeking at a message and dropping it via - KDBUS_RECV_DROP, without installing the passed file + KDBUS_RECV_DROP, without installing the passed file descriptors into the receiving process. - The caller is obliged to call the KDBUS_CMD_FREE + The caller is obliged to call the KDBUS_CMD_FREE ioctl with the returned offset when the memory is no longer needed. @@ -703,9 +711,9 @@ struct kdbus_msg_info { - kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL - kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST - kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL + kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL + kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST + kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL Has exactly one of the aforementioned items attached @@ -721,20 +729,20 @@ struct kdbus_msg_info { When connection A is terminated while connection B is waiting for a reply from it, connection B is notified with a message with an item of - type KDBUS_ITEM_REPLY_DEAD. + type KDBUS_ITEM_REPLY_DEAD. When connection A does not receive a reply from connection B within the specified timeout window, connection A will receive a message with an - item of type KDBUS_ITEM_REPLY_TIMEOUT. + item of type KDBUS_ITEM_REPLY_TIMEOUT. When an ordinary connection (not a monitor) is created on or removed from a bus, messages with an item of type - KDBUS_ITEM_ID_ADD or - KDBUS_ITEM_ID_REMOVE, respectively, are delivered + KDBUS_ITEM_ID_ADD or + KDBUS_ITEM_ID_REMOVE, respectively, are delivered to all bus members that match these messages through their match database. Eavesdroppers (monitor connections) do not cause such notifications to be sent. They are invisible on the bus. @@ -742,9 +750,9 @@ struct kdbus_msg_info { When a connection gains or loses ownership of a name, messages with an - item of type KDBUS_ITEM_NAME_ADD, - KDBUS_ITEM_NAME_REMOVE or - KDBUS_ITEM_NAME_CHANGE are delivered to all bus + item of type KDBUS_ITEM_NAME_ADD, + KDBUS_ITEM_NAME_REMOVE or + KDBUS_ITEM_NAME_CHANGE are delivered to all bus members that match these messages through their match database. @@ -758,11 +766,11 @@ struct kdbus_msg_info { - <varname>KDBUS_CMD_SEND</varname> may fail with the following errors + <constant>KDBUS_CMD_SEND</constant> may fail with the following errors - EOPNOTSUPP + EOPNOTSUPP The connection is not an ordinary connection, or the passed file descriptors are either kdbus handles or unix domain @@ -771,36 +779,37 @@ struct kdbus_msg_info { - EINVAL + EINVAL - The submitted payload type is KDBUS_PAYLOAD_KERNEL, - KDBUS_MSG_EXPECT_REPLY was set without timeout or - cookie values, KDBUS_SEND_SYNC_REPLY was set - without KDBUS_MSG_EXPECT_REPLY, an invalid item - was supplied, src_id was non-zero and was + The submitted payload type is + KDBUS_PAYLOAD_KERNEL, + KDBUS_MSG_EXPECT_REPLY was set without timeout + or cookie values, KDBUS_SEND_SYNC_REPLY was + set without KDBUS_MSG_EXPECT_REPLY, an invalid + item was supplied, src_id was non-zero and was different from the current connection's ID, a supplied memfd had a size of 0, or a string was not properly null-terminated. - ENOTUNIQ + ENOTUNIQ - The supplied destination is KDBUS_DST_ID_BROADCAST, - a file descriptor was passed, KDBUS_MSG_EXPECT_REPLY + The supplied destination is KDBUS_DST_ID_BROADCAST, + a file descriptor was passed, KDBUS_MSG_EXPECT_REPLY was set, or a timeout was given for a broadcast message. - E2BIG + E2BIG Too many items - EMSGSIZE + EMSGSIZE The size of the message header and items or the payload vector is excessive. @@ -808,48 +817,49 @@ struct kdbus_msg_info { - EEXIST + EEXIST - Multiple KDBUS_ITEM_FDS, - KDBUS_ITEM_BLOOM_FILTER or - KDBUS_ITEM_DST_NAME items were supplied. + Multiple KDBUS_ITEM_FDS, + KDBUS_ITEM_BLOOM_FILTER or + KDBUS_ITEM_DST_NAME items were supplied. - EBADF + EBADF - The supplied KDBUS_ITEM_FDS or - KDBUS_ITEM_PAYLOAD_MEMFD items + The supplied KDBUS_ITEM_FDS or + KDBUS_ITEM_PAYLOAD_MEMFD items contained an illegal file descriptor. - EMEDIUMTYPE + EMEDIUMTYPE The supplied memfd is not a sealed kdbus memfd. - EMFILE + EMFILE - Too many file descriptors inside a KDBUS_ITEM_FDS. + Too many file descriptors inside a + KDBUS_ITEM_FDS. - EBADMSG + EBADMSG - An item had illegal size, both a dst_id and a - KDBUS_ITEM_DST_NAME was given, or both a name + An item had illegal size, both a dst_id and a + KDBUS_ITEM_DST_NAME was given, or both a name and a bloom filter was given. - ETXTBSY + ETXTBSY The supplied kdbus memfd file cannot be sealed or the seal was removed, because it is shared with other processes or @@ -859,14 +869,14 @@ struct kdbus_msg_info { - ECOMM + ECOMM A peer does not accept the file descriptors addressed to it. - EFAULT + EFAULT The supplied bloom filter size was not 64-bit aligned or memory supplied by userspace could not be accessed by the kernel. @@ -874,7 +884,7 @@ struct kdbus_msg_info { - EDOM + EDOM The supplied bloom filter size did not match the bloom filter size of the bus. @@ -882,31 +892,31 @@ struct kdbus_msg_info { - EDESTADDRREQ + EDESTADDRREQ - dst_id was set to - KDBUS_DST_ID_NAME, but no - KDBUS_ITEM_DST_NAME was attached. + dst_id was set to + KDBUS_DST_ID_NAME, but no + KDBUS_ITEM_DST_NAME was attached. - ESRCH + ESRCH The name to look up was not found in the name registry. - EADDRNOTAVAIL + EADDRNOTAVAIL - KDBUS_MSG_NO_AUTO_START was given but the + KDBUS_MSG_NO_AUTO_START was given but the destination connection is an activator. - ENXIO + ENXIO The passed numeric destination connection ID couldn't be found, or is not connected. @@ -914,28 +924,28 @@ struct kdbus_msg_info { - ECONNRESET + ECONNRESET The destination connection is no longer active. - ETIMEDOUT + ETIMEDOUT Timeout while synchronously waiting for a reply. - EINTR + EINTR Interrupted system call while synchronously waiting for a reply. - EPIPE + EPIPE When sending a message, a synchronous reply from the receiving connection was expected but the connection died before answering. @@ -943,14 +953,14 @@ struct kdbus_msg_info { - ENOBUFS + ENOBUFS Too many pending messages on the receiver side. - EREMCHG + EREMCHG Both a well-known name and a unique name (ID) was given, but the name is not currently owned by that connection. @@ -958,14 +968,14 @@ struct kdbus_msg_info { - EXFULL + EXFULL The memory pool of the receiver is full. - EREMOTEIO + EREMOTEIO While synchronously waiting for a reply, the remote peer failed with an I/O error. @@ -975,11 +985,11 @@ struct kdbus_msg_info { - <varname>KDBUS_CMD_RECV</varname> may fail with the following errors + <constant>KDBUS_CMD_RECV</constant> may fail with the following errors - EOPNOTSUPP + EOPNOTSUPP The connection is not an ordinary connection, or the passed file descriptors are either kdbus handles or unix domain @@ -988,28 +998,28 @@ struct kdbus_msg_info { - EINVAL + EINVAL Invalid flags or offset. - EAGAIN + EAGAIN No message found in the queue - ENOMSG + ENOMSG No message of the requested priority found. - EOVERFLOW + EOVERFLOW Some messages have been lost. diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml index 64e32fe..6798e4b 100644 --- a/doc/kdbus.names.xml +++ b/doc/kdbus.names.xml @@ -481,11 +481,11 @@ struct kdbus_name_info { - <varname>KDBUS_CMD_NAME_ACQUIRE</varname> may fail with the following errors + <constant>KDBUS_CMD_NAME_ACQUIRE</constant> may fail with the following errors - EINVAL + EINVAL Illegal command flags, illegal name provided, or an activator tried to acquire a second name. @@ -493,28 +493,28 @@ struct kdbus_name_info { - EPERM + EPERM Policy prohibited name ownership. - EALREADY + EALREADY Connection already owns that name. - EEXIST + EEXIST The name already exists and can not be taken over. - E2BIG + E2BIG The maximum number of well-known names per connection is exhausted. @@ -523,25 +523,25 @@ struct kdbus_name_info { - <varname>KDBUS_CMD_NAME_RELEASE</varname> may fail with the following errors + <constant>KDBUS_CMD_NAME_RELEASE</constant> may fail with the following errors - EINVAL + EINVAL Invalid command flags, or invalid name provided. - ESRCH + ESRCH Name is not found in the registry. - EADDRINUSE + EADDRINUSE Name is owned by a different connection and can't be released. @@ -550,18 +550,18 @@ struct kdbus_name_info { - <varname>KDBUS_CMD_NAME_LIST</varname> may fail with the following errors + <constant>KDBUS_CMD_NAME_LIST</constant> may fail with the following errors - EINVAL + EINVAL Invalid command flags - ENOBUFS + ENOBUFS No available memory in the connection's pool. diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index d5364f9..fb0b468 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -188,7 +188,8 @@ struct kdbus_cmd_free { items Items to specify further details for the receive command. - Currently unused. All items will be rejected with -EINVAL. + Currently unused. All items will be rejected with + -EINVAL. @@ -202,29 +203,29 @@ struct kdbus_cmd_free { - <varname>KDBUS_CMD_FREE</varname> may fail with the following errors + <constant>KDBUS_CMD_FREE</constant> may fail with the following errors - ENXIO + ENXIO No pool slice found at given offset. - EINVAL + EINVAL Invalid flags provided. - EINVAL + EINVAL The offset is valid, but the user is not allowed to free the slice. This happens, for example, if the offset was retrieved with - KDBUS_RECV_PEEK. + KDBUS_RECV_PEEK. -- 2.34.1