summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Mack <daniel@zonque.org>2015-01-28 23:14:41 (GMT)
committerDaniel Mack <daniel@zonque.org>2015-01-28 23:14:41 (GMT)
commited9048f201b264da2b0a6dcabf52b2bfed88a1b4 (patch)
tree87602eeba84c55d33132632f88817c715b5097fa
parentdf1c1bf855795b34e39d7ae236fcce93c3e6ed72 (diff)
downloadkdbus-bus-upstream.zip
kdbus-bus-upstream.tar.gz
kdbus-bus-upstream.tar.bz2
doc: annotate more strings, break more lines ...upstream/0.20150129.081441utcupstream
Signed-off-by: Daniel Mack <daniel@zonque.org>
-rw-r--r--doc/kdbus.connection.xml3
-rw-r--r--doc/kdbus.item.xml35
-rw-r--r--doc/kdbus.message.xml57
-rw-r--r--doc/kdbus.names.xml11
-rw-r--r--doc/kdbus.pool.xml4
-rw-r--r--doc/kdbus.xml4
6 files changed, 60 insertions, 54 deletions
diff --git a/doc/kdbus.connection.xml b/doc/kdbus.connection.xml
index 270eccaa..666cbe4 100644
--- a/doc/kdbus.connection.xml
+++ b/doc/kdbus.connection.xml
@@ -134,7 +134,8 @@
on the same bus by using the peer's connection ID as the destination.
</para>
<para>
- The KDBUS_CMD_HELLO ioctl takes the following struct as argument.
+ The <constant>KDBUS_CMD_HELLO</constant> ioctl takes a <type>struct
+ kdbus_cmd_hello</type> as argument.
</para>
<programlisting>
diff --git a/doc/kdbus.item.xml b/doc/kdbus.item.xml
index 9f8ed9c..3222ae1 100644
--- a/doc/kdbus.item.xml
+++ b/doc/kdbus.item.xml
@@ -500,36 +500,33 @@ struct kdbus_pids {
<varlistentry>
<term><constant>KDBUS_ITEM_TID_COMM</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>comm</emphasis> of a task's
- <emphasis>TID</emphasis>, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>TID</emphasis> (thread ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>KDBUS_ITEM_PID_COMM</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>comm</emphasis> of a task's
- <emphasis>PID</emphasis>, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>comm</emphasis> string of a task's
+ <emphasis>PID</emphasis> (process ID), stored as null-terminated
+ string in <varname>item.str</varname>. Its length can also be
+ derived from the item's total size. Receivers of this item should
+ not use its contents for any kind of security measures. See below.
</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>KDBUS_ITEM_EXE</constant> [*]</term>
<listitem><para>
- Contains the <emphasis>path to the executable</emphasis> of a
- task, stored as null-terminated string in
- <varname>item.str</varname>. Its length can also be derived from
- the item's total size.
- Receivers of this item should not use its contents for any kind
- of security measures. See below.
+ Contains the <emphasis>path to the executable</emphasis> of a task,
+ stored as null-terminated string in <varname>item.str</varname>. Its
+ length can also be derived from the item's total size. Receivers of
+ this item should not use its contents for any kind of security
+ measures. See below.
</para></listitem>
</varlistentry>
@@ -719,6 +716,8 @@ struct kdbus_notify_id_change {
<varname>new_id</varname> describes the new owner of the name and
is set to <constant>0</constant> values in case of
<constant>KDBUS_ITEM_NAME_REMOVE</constant>.
+ The <varname>name</varname> field contains the well-known name the
+ notification is about, as null-terminated string.
See
<citerefentry>
<refentrytitle>kdbus.match</refentrytitle>
diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml
index 7a9f9f1..d33c00a 100644
--- a/doc/kdbus.message.xml
+++ b/doc/kdbus.message.xml
@@ -68,18 +68,25 @@ struct kdbus_cmd_send {
<listitem>
<para>
By default, all calls to kdbus are considered asynchronous,
- non-blocking. However, as there are many use cases that need to wait
- for a remote peer to answer a method call, there's a way to send a
- message and wait for a reply in a synchronous fashion. This is what
- the KDBUS_SEND_SYNC_REPLY controls. The KDBUS_CMD_SEND ioctl will block
- until the reply has arrived, the timeout limit is reached, in case the
- remote connection was shut down, or if interrupted by a signal before
- any reply; see signal(7).
-
- The offset of the reply message in the sender's pool is stored in in
- 'offset_reply' when the ioctl has returned without error. Hence, there
- is no need for another KDBUS_CMD_RECV ioctl or anything else to receive
- the reply.
+ non-blocking. However, as there are many use cases that need
+ to wait for a remote peer to answer a method call, there's a
+ way to send a message and wait for a reply in a synchronous
+ fashion. This is what the
+ <constant>KDBUS_SEND_SYNC_REPLY</constant> controls. The
+ <constant>KDBUS_CMD_SEND</constant> ioctl will block until the
+ reply has arrived, the timeout limit is reached, in case the
+ remote connection was shut down, or if interrupted by a signal
+ before any reply; see
+ <citerefentry>
+ <refentrytitle>signal</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </citerefentry>.
+
+ The offset of the reply message in the sender's pool is stored
+ in in <varname>offset_reply</varname> when the ioctl has
+ returned without error. Hence, there is no need for another
+ <constant>KDBUS_CMD_RECV</constant> ioctl or anything else to
+ receive the reply.
</para>
</listitem>
</varlistentry>
@@ -501,9 +508,10 @@ struct kdbus_msg {
<title>Receiving messages</title>
<para>
- Messages are received by the client with the KDBUS_CMD_RECV ioctl.
- The endpoint file of the bus supports <emphasis>poll/epoll/select</emphasis>
- to wake up the receiving process when new messages are queued up to be received.
+ Messages are received by the client with the
+ <constant>KDBUS_CMD_RECV</constant> ioctl. The endpoint file of the bus
+ supports <function>poll()/epoll()/select()</function> to wake up the
+ receiving process when new messages are queued up to be received.
</para>
<para>
@@ -740,14 +748,23 @@ struct kdbus_msg_info {
</para>
<itemizedlist mark='opencircle'>
- <listitem><para>kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant></para></listitem>
- <listitem><para>kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant></para></listitem>
- <listitem><para>kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant></para></listitem>
- <listitem><para>Has exactly one of the aforementioned items attached</para></listitem>
+ <listitem><para>
+ kdbus_msg.src_id == <constant>KDBUS_SRC_ID_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ kdbus_msg.dst_id == <constant>KDBUS_DST_ID_BROADCAST</constant>
+ </para></listitem>
+ <listitem>
+ <para>kdbus_msg.payload_type == <constant>KDBUS_PAYLOAD_KERNEL</constant>
+ </para></listitem>
+ <listitem><para>
+ Has exactly one of the aforementioned items attached
+ </para></listitem>
</itemizedlist>
<para>
- Kernel notifications have an item of type KDBUS_ITEM_TIMESTAMP attached.
+ Kernel notifications have an item of type
+ <constant>KDBUS_ITEM_TIMESTAMP</constant> attached.
</para>
<para>
diff --git a/doc/kdbus.names.xml b/doc/kdbus.names.xml
index 5736bd0..1a28fb0 100644
--- a/doc/kdbus.names.xml
+++ b/doc/kdbus.names.xml
@@ -227,21 +227,10 @@ struct kdbus_cmd_name {
<programlisting>
struct kdbus_cmd_name {
__u64 size;
- The overall size of this struct, including the null-terminated name string.
-
__u64 flags;
- Flags to the command. Currently unused and must be zero.
-
__u64 kernel_flags;
- Valid flags for this command, returned by the kernel upon each call.
-
__u64 return_flags;
- Flags returned by the kernel. Currently unused and always set to zero by
- the kernel.
-
struct kdbus_item items[0];
- Items to submit the name. Currently, one item of type KDBUS_ITEM_NAME is
- expected and allowed, and the contained string must be a valid bus name.
};
</programlisting>
diff --git a/doc/kdbus.pool.xml b/doc/kdbus.pool.xml
index 8fa2a86..de222f2 100644
--- a/doc/kdbus.pool.xml
+++ b/doc/kdbus.pool.xml
@@ -28,7 +28,7 @@
<constant>KDBUS_ITEM_BLOOM_PARAMETER</constant> item that is returned by
<constant>KDBUS_CMD_HELLO</constant>. Internally, the pool is segmented
into <emphasis>slices</emphasis>, each referenced by its
- <emphasis>offset</emphasis> in the pool.
+ <emphasis>offset</emphasis> in the pool, expressed in <type>bytes</type>.
</para>
<para>
@@ -108,7 +108,7 @@ uint8_t *buf = mmap(NULL, POOL_SIZE, PROT_READ, MAP_SHARED, conn_fd, 0);
<para>
Alternatively, instead of mapping the entire pool buffer, only parts
of it can be mapped. Every kdbus command that returns an
- <emphasis> offset</emphasis> (see above) also reports a
+ <emphasis>offset</emphasis> (see above) also reports a
<emphasis>size</emphasis> along with it, so userspace can be written
in a way that it only maps portions of the part to access a specific
<emphasis>slice</emphasis>.
diff --git a/doc/kdbus.xml b/doc/kdbus.xml
index 2b85b5d..a64d4e6 100644
--- a/doc/kdbus.xml
+++ b/doc/kdbus.xml
@@ -213,8 +213,8 @@
counter-part blob, called a 'filter', and signals are only delivered to
peers which have a match that whitelists the message's filter. Senders
of signal messages can use either a single connection ID as receiver, or
- KDBUS_DST_ID_BROADCAST to potentially send it to all connections of a
- bus, following the logic described above. See
+ <constant>KDBUS_DST_ID_BROADCAST</constant> to potentially send it to
+ all connections of a bus, following the logic described above. See
<citerefentry>
<refentrytitle>kdbus.match</refentrytitle>
<manvolnum>7</manvolnum>