From c0d91fab0eafe85d17325bc4c92eeea14220782c Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Tue, 27 Jan 2015 18:11:35 +0100 Subject: doc: reformat the "return value" sections in all man pages Also fix some more TODOs. Signed-off-by: Daniel Mack --- doc/kdbus.bus.xml | 74 +++---- doc/kdbus.connection.xml | 314 ++++++++++++++-------------- doc/kdbus.endpoint.xml | 89 +++++--- doc/kdbus.match.xml | 90 ++++---- doc/kdbus.message.xml | 518 +++++++++++++++++++++++------------------------ doc/kdbus.names.xml | 177 ++++++++-------- doc/kdbus.pool.xml | 50 ++--- 7 files changed, 683 insertions(+), 629 deletions(-) diff --git a/doc/kdbus.bus.xml b/doc/kdbus.bus.xml index 42a140a15a8..92571f62f4e 100644 --- a/doc/kdbus.bus.xml +++ b/doc/kdbus.bus.xml @@ -209,48 +209,48 @@ struct kdbus_cmd_make { On success, all mentioned ioctl commands return 0. - - KDBUS_CMD_BUS_MAKE may return the following errors. - + + <varname>KDBUS_CMD_BUS_MAKE</varname> may return the following errors - - - -EBADMSG - - A mandatory item is missing. - - + + + -EBADMSG + + A mandatory item is missing. + + - - -EINVAL - - The flags supplied in the struct kdbus_cmd_make - are invalid or the supplied name does not start with the current - UID and a '-'. - - + + -EINVAL + + The flags supplied in the struct kdbus_cmd_make + are invalid or the supplied name does not start with the current + UID and a '-'. + + - - -EEXIST - - A bus of that name already exists. - - + + -EEXIST + + A bus of that name already exists. + + - - -ESHUTDOWN - - The kdbus mount instance for the bus was already shut down. - - + + -ESHUTDOWN + + The kdbus mount instance for the bus was already shut down. + + - - -EMFILE - - The maximum number of buses for the current user is exhausted. - - - + + -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 133022e4ce9..2b2d85e1e0b 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -241,7 +241,11 @@ struct kdbus_cmd_hello { attach_flags_recv Request the attachment of metadata for each message received by this - connection. See XXX TODO XXX for more details. + connection. See + kdbus7 + for information about metadata, and + kdbus.item7 + regarding items in general. @@ -317,7 +321,9 @@ struct kdbus_cmd_hello { For activators and policy holders only, combinations of - these two items describe policy access entries. See XXX TODO XXX. + these two items describe policy access entries. See + kdbus.policy7 + for further details. @@ -807,152 +813,164 @@ struct kdbus_cmd_update { On success, all metioned ioctl commands return 0. - - KDBUS_CMD_HELLO may return the following errors. - - - - - -EFAULT - - The supplied pool size was 0 or not a multiple of the page size. - - - - - -EINVAL - - The flags supplied in struct kdbus_cmd_make are - invalid, or an illegal combination of - KDBUS_HELLO_MONITOR, - KDBUS_HELLO_ACTIVATOR and - KDBUS_HELLO_POLICY_HOLDER was passed in the flags, - or an invalid set of items was supplied. - - - - - -ECONNREFUSED - - The attach_flags_send field did not satisfy the requirements of - the bus. - - - - - -EPERM - - A KDBUS_ITEM_CREDS items was supplied, but the - current user is not privileged. - - - - - -ESHUTDOWN - - The bus you were trying to connect to has already been shut down. - - - - - -EMFILE - - The maximum number of connections on the bus has been reached. - - - - - -EOPNOTSUPP - - The endpoint does not support the connection flags supplied in - struct kdbus_cmd_hello. - - - - - - KDBUS_CMD_BYEBYE may return the following errors. - - - - - -EALREADY - - The connection has already been shut down. - - - - - -EBUSY - - There are still messages queued up in the connection's pool. - - - - - - KDBUS_CMD_CONN_INFO may return the following errors. - - - - - -EINVAL - - Invalid flags, or neither an ID nor a name was provided, or the - name is invalid. - - - - - -ESRCH - - Connection lookup by name failed. - - - - - -ENXIO - - No connection with the provided connection ID found. - - - - - - KDBUS_CMD_CONN_UPDATE may return the following errors. - - - - - -EINVAL - - Illegal flags or items. - - - - - -EINVAL - - Wildcards submitted in policy entries, or illegal sequence - of policy items. - - - - - -EOPNOTSUPP - - Operation not supported by connection. - - - - - -E2BIG - - Too many policy items attached. - - - - + + <varname>KDBUS_CMD_HELLO</varname> may return the following errors + + + + -EFAULT + + The supplied pool size was 0 or not a multiple of the page size. + + + + + -EINVAL + + The flags supplied in struct kdbus_cmd_make are + invalid. + + + + + -EINVAL + + An illegal combination of + KDBUS_HELLO_MONITOR, + KDBUS_HELLO_ACTIVATOR and + KDBUS_HELLO_POLICY_HOLDER was passed in the flags. + + + + + -EINVAL + + An invalid set of items was supplied. + + + + + -ECONNREFUSED + + The attach_flags_send field did not satisfy the requirements of + the bus. + + + + + -EPERM + + A KDBUS_ITEM_CREDS items was supplied, but the + current user is not privileged. + + + + + -ESHUTDOWN + + The bus you were trying to connect to has already been shut down. + + + + + -EMFILE + + The maximum number of connections on the bus has been reached. + + + + + -EOPNOTSUPP + + The endpoint does not support the connection flags supplied in + struct kdbus_cmd_hello. + + + + + + + <varname>KDBUS_CMD_BYEBYE</varname> may return the following errors + + + + -EALREADY + + The connection has already been shut down. + + + + + -EBUSY + + There are still messages queued up in the connection's pool. + + + + + + + <varname>KDBUS_CMD_CONN_INFO</varname> may return the following errors + + + + -EINVAL + + Invalid flags, or neither an ID nor a name was provided, or the + name is invalid. + + + + + -ESRCH + + Connection lookup by name failed. + + + + + -ENXIO + + No connection with the provided connection ID found. + + + + + + + <varname>KDBUS_CMD_CONN_UPDATE</varname> may return the following errors + + + + -EINVAL + + Illegal flags or items. + + + + + -EINVAL + + Wildcards submitted in policy entries, or illegal sequence + of policy items. + + + + + -EOPNOTSUPP + + Operation not supported by connection. + + + + + -E2BIG + + Too many policy items attached. + + + + diff --git a/doc/kdbus.endpoint.xml b/doc/kdbus.endpoint.xml index 7007ae489d7..8ab7540a1f5 100644 --- a/doc/kdbus.endpoint.xml +++ b/doc/kdbus.endpoint.xml @@ -259,35 +259,72 @@ struct kdbus_cmd_make { On success, all mentioned ioctl commands return 0. - - KDBUS_CMD_ENDPOINT_MAKE may return the following errors. - + + <varname>KDBUS_CMD_ENDPOINT_MAKE</varname> may return the following errors - - - -EINVAL - - The flags supplied in the struct kdbus_cmd_make - are invalid. - - + + + -EINVAL + + The flags supplied in the struct kdbus_cmd_make + are invalid. + + - - -EEXIST - - An endpoint of that name already exists. - - + + -EINVAL + + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. + + - - -EPERM - - The calling user is not privileged. See - kdbus7 - for information about privileged users. - - - + + -EEXIST + + An endpoint of that name already exists. + + + + + -EPERM + + The calling user is not privileged. See + kdbus7 + for information about privileged users. + + + + + + + <varname>KDBUS_CMD_ENDPOINT_UPDATE</varname> may return the following errors + + + + -EINVAL + + The flags supplied in the struct kdbus_cmd_update + are invalid. + + + + + -EINVAL + + Illegal combination of KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS was provided. + + + + + -EEXIST + + An endpoint of that name already exists. + + + + diff --git a/doc/kdbus.match.xml b/doc/kdbus.match.xml index 647eb2faf75..e260fdd6a2a 100644 --- a/doc/kdbus.match.xml +++ b/doc/kdbus.match.xml @@ -400,52 +400,52 @@ struct kdbus_cmd_match { On success, all mentioned ioctl commands return 0. - - KDBUS_CMD_MATCH_ADD may return the following errors. - - - - - -EINVAL - - Illegal flags or items. - - - - - -EDOM - - Illegal bloom filter size. - - - - - -EMFILE - - Too many matches for this connection. - - - - - - KDBUS_CMD_MATCH_REMOVE may return the following errors. - - - - - -EINVAL - - Illegal flags. - - + + <varname>KDBUS_CMD_MATCH_ADD</varname> may return the following errors + + + + -EINVAL + + Illegal flags or items. + + + + + -EDOM + + Illegal bloom filter size. + + + + + -EMFILE + + Too many matches for this connection. + + + + - - -EBADSLT - - A match entry with the given cookie could not be found. - - - + + <varname>KDBUS_CMD_MATCH_REMOVE</varname> may return the following errors + + + + -EINVAL + + Illegal flags. + + + + + -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 4e759152eae..3482961a5da 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -756,265 +756,265 @@ struct kdbus_msg_info { On success, all metioned ioctl commands return 0. - - KDBUS_CMD_SEND may return the following errors. - - - - - -EOPNOTSUPP - - The connection is not an ordinary connection, or the passed - file descriptors are either kdbus handles or unix domain - sockets. Both are currently unsupported. - - - - - -EINVAL - - The submitted payload type is KDBUS_PAYLOAD_KERNEL, - KDBUS_MSG_EXPECT_REPLY was set without timeout or - cookie values, KDBUS_SEND_SYNC_REPLY was set - without KDBUS_MSG_EXPECT_REPLY, an invalid item - was supplied, src_id was non-zero and was - different from the current connection's ID, a supplied memfd had a - size of 0, or a string was not properly null-terminated. - - - - - -ENOTUNIQ - - The supplied destination is KDBUS_DST_ID_BROADCAST, - a file descriptor was passed, KDBUS_MSG_EXPECT_REPLY - was set, or a timeout was given for a broadcast message. - - - - - -E2BIG - - Too many items - - - - - -EMSGSIZE - - The size of the message header and items or the payload vector - is excessive. - - - - - -EEXIST - - Multiple KDBUS_ITEM_FDS, - KDBUS_ITEM_BLOOM_FILTER or - KDBUS_ITEM_DST_NAME items were supplied. - - - - - -EBADF - - The supplied KDBUS_ITEM_FDS or - KDBUS_ITEM_PAYLOAD_MEMFD items - contained an illegal file descriptor. - - - - - -EMEDIUMTYPE - - The supplied memfd is not a sealed kdbus memfd. - - - - - -EMFILE - - Too many file descriptors inside a KDBUS_ITEM_FDS. - - - - - -EBADMSG - - An item had illegal size, both a dst_id and a - KDBUS_ITEM_DST_NAME was given, or both a name - and a bloom filter was given. - - - - - -ETXTBSY - - The supplied kdbus memfd file cannot be sealed or the seal - was removed, because it is shared with other processes or - still mapped with - mmap2. - - - - - -ECOMM - - A peer does not accept the file descriptors addressed to it. - - - - - -EFAULT - - The supplied bloom filter size was not 64-bit aligned or memory - supplied by userspace could not be accessed by the kernel. - - - - - -EDOM - - The supplied bloom filter size did not match the bloom filter - size of the bus. - - - - - -EDESTADDRREQ - - dst_id was set to - KDBUS_DST_ID_NAME, but no - KDBUS_ITEM_DST_NAME was attached. - - - - - -ESRCH - - The name to look up was not found in the name registry. - - - - - -EADDRNOTAVAIL - - KDBUS_MSG_NO_AUTO_START was given but the - destination connection is an activator. - - - - - -ENXIO - - The passed numeric destination connection ID couldn't be found, - or is not connected. - - - - - -ECONNRESET - - The destination connection is no longer active. - - - - - -ETIMEDOUT - - Timeout while synchronously waiting for a reply. - - - - - -EINTR - - Interrupted system call while synchronously waiting for a reply. - - - - - -EPIPE - - When sending a message, a synchronous reply from the receiving - connection was expected but the connection died before answering. - - - - - -ENOBUFS - - Too many pending messages on the receiver side. - - - - - -EREMCHG - - Both a well-known name and a unique name (ID) was given, but - the name is not currently owned by that connection. - - - - - -EXFULL - - The memory pool of the receiver is full. - - - - - -EREMOTEIO - - While synchronously waiting for a reply, the remote peer - failed with an I/O error. - - - - - - KDBUS_CMD_RECV may return the following errors. - - - - - -EOPNOTSUPP - - The connection is not an ordinary connection, or the passed - file descriptors are either kdbus handles or unix domain - sockets. Both are currently unsupported. - - - - - -EINVAL - - Invalid flags or offset. - - - - - -EAGAIN - - No message found in the queue - - - - - -ENOMSG - - No message of the requested priority found. - - - - - -EOVERFLOW - - Some messages have been lost. - - - + + <varname>KDBUS_CMD_SEND</varname> may return the following errors + + + + -EOPNOTSUPP + + The connection is not an ordinary connection, or the passed + file descriptors are either kdbus handles or unix domain + sockets. Both are currently unsupported. + + + + + -EINVAL + + The submitted payload type is KDBUS_PAYLOAD_KERNEL, + KDBUS_MSG_EXPECT_REPLY was set without timeout or + cookie values, KDBUS_SEND_SYNC_REPLY was set + without KDBUS_MSG_EXPECT_REPLY, an invalid item + was supplied, src_id was non-zero and was + different from the current connection's ID, a supplied memfd had a + size of 0, or a string was not properly null-terminated. + + + + + -ENOTUNIQ + + The supplied destination is KDBUS_DST_ID_BROADCAST, + a file descriptor was passed, KDBUS_MSG_EXPECT_REPLY + was set, or a timeout was given for a broadcast message. + + + + + -E2BIG + + Too many items + + + + + -EMSGSIZE + + The size of the message header and items or the payload vector + is excessive. + + + + + -EEXIST + + Multiple KDBUS_ITEM_FDS, + KDBUS_ITEM_BLOOM_FILTER or + KDBUS_ITEM_DST_NAME items were supplied. + + + + + -EBADF + + The supplied KDBUS_ITEM_FDS or + KDBUS_ITEM_PAYLOAD_MEMFD items + contained an illegal file descriptor. + + + + + -EMEDIUMTYPE + + The supplied memfd is not a sealed kdbus memfd. + + + + + -EMFILE + + Too many file descriptors inside a KDBUS_ITEM_FDS. + + + + + -EBADMSG + + An item had illegal size, both a dst_id and a + KDBUS_ITEM_DST_NAME was given, or both a name + and a bloom filter was given. + + + + + -ETXTBSY + + The supplied kdbus memfd file cannot be sealed or the seal + was removed, because it is shared with other processes or + still mapped with + mmap2. + + + + + -ECOMM + + A peer does not accept the file descriptors addressed to it. + + + + + -EFAULT + + The supplied bloom filter size was not 64-bit aligned or memory + supplied by userspace could not be accessed by the kernel. + + + + + -EDOM + + The supplied bloom filter size did not match the bloom filter + size of the bus. + + + + + -EDESTADDRREQ + + dst_id was set to + KDBUS_DST_ID_NAME, but no + KDBUS_ITEM_DST_NAME was attached. + + + + + -ESRCH + + The name to look up was not found in the name registry. + + + + + -EADDRNOTAVAIL + + KDBUS_MSG_NO_AUTO_START was given but the + destination connection is an activator. + + + + + -ENXIO + + The passed numeric destination connection ID couldn't be found, + or is not connected. + + + + + -ECONNRESET + + The destination connection is no longer active. + + + + + -ETIMEDOUT + + Timeout while synchronously waiting for a reply. + + + + + -EINTR + + Interrupted system call while synchronously waiting for a reply. + + + + + -EPIPE + + When sending a message, a synchronous reply from the receiving + connection was expected but the connection died before answering. + + + + + -ENOBUFS + + Too many pending messages on the receiver side. + + + + + -EREMCHG + + Both a well-known name and a unique name (ID) was given, but + the name is not currently owned by that connection. + + + + + -EXFULL + + The memory pool of the receiver is full. + + + + + -EREMOTEIO + + While synchronously waiting for a reply, the remote peer + failed with an I/O error. + + + + + + + <varname>KDBUS_CMD_RECV</varname> may return the following errors + + + + -EOPNOTSUPP + + The connection is not an ordinary connection, or the passed + file descriptors are either kdbus handles or unix domain + sockets. Both are currently unsupported. + + + + + -EINVAL + + Invalid flags or offset. + + + + + -EAGAIN + + No message found in the queue + + + + + -ENOMSG + + No message of the requested priority found. + + + + + -EOVERFLOW + + Some messages have been lost. + + + + diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml index f2c4c63fb88..09f0c7a683c 100644 --- a/doc/kdbus.names.xml +++ b/doc/kdbus.names.xml @@ -479,95 +479,94 @@ struct kdbus_name_info { On success, all metioned ioctl commands return 0. - - KDBUS_CMD_NAME_ACQUIRE may return the following errors. - - - - - -EINVAL - - Illegal command flags, illegal name provided, or an activator - tried to acquire a second name. - - - - - -EPERM - - Policy prohibited name ownership. - - - - - -EALREADY - - Connection already owns that name. - - - - - -EEXIST - - The name already exists and can not be taken over. - - - - - -E2BIG - - The maximum number of well-known names per connection is exhausted. - - - - - - KDBUS_CMD_NAME_RELEASE may return the following errors. - - - - - -EINVAL - - Invalid command flags, or invalid name provided. - - - - - -ESRCH - - Name is not found in the registry. - - - - - -EADDRINUSE - - Name is owned by a different connection and can't be released. - - - - - - KDBUS_CMD_NAME_LIST may return the following errors. - - - - - -EINVAL - - Invalid command flags - - - - - -ENOBUFS - - No available memory in the connection's pool. - - - - + + <varname>KDBUS_CMD_NAME_ACQUIRE</varname> may return the following errors + + + + -EINVAL + + Illegal command flags, illegal name provided, or an activator + tried to acquire a second name. + + + + + -EPERM + + Policy prohibited name ownership. + + + + + -EALREADY + + Connection already owns that name. + + + + + -EEXIST + + The name already exists and can not be taken over. + + + + + -E2BIG + + The maximum number of well-known names per connection is exhausted. + + + + + + + <varname>KDBUS_CMD_NAME_RELEASE</varname> may return the following errors + + + + -EINVAL + + Invalid command flags, or invalid name provided. + + + + + -ESRCH + + Name is not found in the registry. + + + + + -EADDRINUSE + + Name is owned by a different connection and can't be released. + + + + + + + <varname>KDBUS_CMD_NAME_LIST</varname> may return the following errors + + + + -EINVAL + + Invalid command flags + + + + + -ENOBUFS + + No available memory in the connection's pool. + + + + diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml index 167727fec43..73957206823 100644 --- a/doc/kdbus.pool.xml +++ b/doc/kdbus.pool.xml @@ -163,34 +163,34 @@ struct kdbus_cmd_free { On success, all metioned ioctl commands return 0. - - KDBUS_CMD_FREE may return the following errors. - + + <varname>KDBUS_CMD_FREE</varname> may return the following errors - - - -ENXIO - - No pool slice found at given offset. - - + + + -ENXIO + + No pool slice found at given offset. + + - - -EINVAL - - Invalid flags provided. - - + + -EINVAL + + Invalid flags provided. + + - - -EINVAL - - The offset is valid, but the user is not allowed to free the slice. - This happens, for example, if the offset was retrieved with - KDBUS_RECV_PEEK. - - - + + -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. + + + + -- cgit v1.2.3