From da36403b8bf12b11fbaa8bb6f0b732448ec05c73 Mon Sep 17 00:00:00 2001 From: Tom Gundersen Date: Tue, 27 Jan 2015 19:46:05 +0100 Subject: [PATCH] doc: minor changes to kdbus.connection(7) Signed-off-by: Tom Gundersen --- doc/kdbus.connection.xml | 53 ++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml index 2b2d85e..4160c4d 100644 --- a/doc/kdbus.connection.xml +++ b/doc/kdbus.connection.xml @@ -37,10 +37,11 @@ Messages with a specific uint64_t destination ID are directly delivered to the connection with the corresponding ID. Messages with the special destination ID KDBUS_DST_ID_BROADCAST - are broadcast messages and are potentially delivered to all currently - active connections on the bus. However, in order to receive any broadcast - messages, clients must subscribe to the specific messages in which they are - interested in. + (~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 @@ -56,9 +57,9 @@ on name acquisition, the name registry, and the validity of names. - Messages can specify the special destination ID 0 and carry a well-known name - in the message data. Such a message is delivered to the destination connection - which owns that well-known name. + 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. Creating connections - A connection to a bus is created by opening an endpoint file of a bus and - becoming an active client with the KDBUS_CMD_HELLO - ioctl. Every connected client connection has a unique identifier on the - bus and can address messages to every other connection on the same bus - by using the peer's connection ID as the destination. + A connection to a bus is created by opening an endpoint file (see + kdbus.endpoint7) + of a bus and becoming an active client with the KDBUS_CMD_HELLO + ioctl. Every connection has a unique identifier on the bus and can address + messages to every other connection on the same bus by using the peer's + connection ID as the destination. The KDBUS_CMD_HELLO ioctl takes the following struct as argument. @@ -152,16 +154,17 @@ struct kdbus_cmd_hello { flags - Flags to apply to this connection + Flags to apply to this connection +TODO: document precisely what combination of flags may be passed KDBUS_HELLO_ACCEPT_FD When this flag is set, the connection can be sent file - descriptors as message payload. If it's not set, an attempt - to send file descriptors results in -ECOMM - on the sender's side. + 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. @@ -194,12 +197,11 @@ struct kdbus_cmd_hello { KDBUS_HELLO_MONITOR - Make this connection an monitor (eavesdropping) connection. - See the section below more information. + Make this connection a monitor (eavesdropping) connection. This flag can only be set by privileged bus connections. See - below. + below for more information. @@ -227,13 +229,12 @@ struct kdbus_cmd_hello { Set the bits for metadata this connection permits to be sent to the receiving peer. Only metadata items that are both allowed to be sent - by the sender and that are requested by the receiver will effectively - be attached to the message. Note, however, that the bus may - optionally require some of those bits to be set. If the match fails, - -ECONNREFUSED will be returned. In either case, - this field will be set to the mask of metadata items that are - enforced by the bus. The KDBUS_FLAGS_KERNEL bit - will as well be set. + 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. -- 2.34.1