man: add kdbus man-pageskdbus

WIP

6 files changed, 457 insertions, 0 deletions

diff --git a/Makefile-man.am b/Makefile-man.am
index 105853e47..3f2dc367d 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -16,6 +16,11 @@ MANPAGES += \
 	man/hostname.5 \
 	man/journalctl.1 \
 	man/journald.conf.5 \
+	man/kdbus.7 \
+	man/kdbus.bus.7 \
+	man/kdbus.connection.7 \
+	man/kdbus.fs.7 \
+	man/kdbus.message.7 \
 	man/kernel-command-line.7 \
 	man/kernel-install.8 \
 	man/locale.conf.5 \
@@ -152,6 +157,7 @@ MANPAGES_ALIAS += \
 	man/SD_WARNING.3 \
 	man/init.1 \
 	man/journald.conf.d.5 \
+	man/kdbusfs.7 \
 	man/poweroff.8 \
 	man/reboot.8 \
 	man/sd_id128_equal.3 \
@@ -265,6 +271,7 @@ man/SD_NOTICE.3: man/sd-daemon.3
 man/SD_WARNING.3: man/sd-daemon.3
 man/init.1: man/systemd.1
 man/journald.conf.d.5: man/journald.conf.5
+man/kdbusfs.7: man/kdbus.fs.7
 man/poweroff.8: man/halt.8
 man/reboot.8: man/halt.8
 man/sd_id128_equal.3: man/sd-id128.3
@@ -432,6 +439,9 @@ man/init.html: man/systemd.html
 man/journald.conf.d.html: man/journald.conf.html
 	$(html-alias)
 
+man/kdbusfs.html: man/kdbus.fs.html
+	$(html-alias)
+
 man/poweroff.html: man/halt.html
 	$(html-alias)
 
@@ -1630,6 +1640,11 @@ EXTRA_DIST += \
 	man/hwdb.xml \
 	man/journalctl.xml \
 	man/journald.conf.xml \
+	man/kdbus.bus.xml \
+	man/kdbus.connection.xml \
+	man/kdbus.fs.xml \
+	man/kdbus.message.xml \
+	man/kdbus.xml \
 	man/kernel-command-line.xml \
 	man/kernel-install.xml \
 	man/less-variables.xml \
diff --git a/man/kdbus.bus.xml b/man/kdbus.bus.xml
new file mode 100644
index 000000000..27a03671b
--- /dev/null
+++ b/man/kdbus.bus.xml
@@ -0,0 +1,66 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="kdbus.bus">
+
+        <refentryinfo>
+                <title>kdbus.bus</title>
+                <productname>kdbus</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>David</firstname>
+                                <surname>Herrmann</surname>
+                                <email>dh.herrmann@gmail.com</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>kdbus.bus</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>kdbus.bus</refname>
+                <refpurpose>Kernel Message Buses</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>kdbus bus</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/kdbus.connection.xml b/man/kdbus.connection.xml
new file mode 100644
index 000000000..ff52cae47
--- /dev/null
+++ b/man/kdbus.connection.xml
@@ -0,0 +1,66 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="kdbus.connection">
+
+        <refentryinfo>
+                <title>kdbus.connection</title>
+                <productname>kdbus</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>David</firstname>
+                                <surname>Herrmann</surname>
+                                <email>dh.herrmann@gmail.com</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>kdbus.connection</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>kdbus.connection</refname>
+                <refpurpose>Kernel Message Bus Connections</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>kdbus connection</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/kdbus.fs.xml b/man/kdbus.fs.xml
new file mode 100644
index 000000000..f06b73013
--- /dev/null
+++ b/man/kdbus.fs.xml
@@ -0,0 +1,67 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="kdbus.fs">
+
+        <refentryinfo>
+                <title>kdbus.fs</title>
+                <productname>kdbus</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>David</firstname>
+                                <surname>Herrmann</surname>
+                                <email>dh.herrmann@gmail.com</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>kdbus.fs</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>kdbus.fs</refname>
+                <refname>kdbusfs</refname>
+                <refpurpose>Kernel Message Bus Pseudo File-system</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>kdbusfs</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/kdbus.message.xml b/man/kdbus.message.xml
new file mode 100644
index 000000000..79737ad71
--- /dev/null
+++ b/man/kdbus.message.xml
@@ -0,0 +1,66 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="kdbus.message">
+
+        <refentryinfo>
+                <title>kdbus.message</title>
+                <productname>kdbus</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>David</firstname>
+                                <surname>Herrmann</surname>
+                                <email>dh.herrmann@gmail.com</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>kdbus.message</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>kdbus.message</refname>
+                <refpurpose>Kernel Bus Messages</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>kdbus message</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>kdbus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/kdbus.xml b/man/kdbus.xml
new file mode 100644
index 000000000..7c442bf8c
--- /dev/null
+++ b/man/kdbus.xml
@@ -0,0 +1,177 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2014 David Herrmann <dh.herrmann@gmail.com>
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="kdbus">
+
+        <refentryinfo>
+                <title>kdbus</title>
+                <productname>kdbus</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>David</firstname>
+                                <surname>Herrmann</surname>
+                                <email>dh.herrmann@gmail.com</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>kdbus</refentrytitle>
+                <manvolnum>7</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>kdbus</refname>
+                <refpurpose>Kernel Message Bus</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>kdbus is an inter-process communication bus system
+                controlled by the kernel. It provides user-space with a bus API
+                to send unicast and multicast messages to one, or many, peers
+                connected to the same bus.
+                It does not enforce any layout on the transmitted data, but
+                only provides the transport layer used for message interchange
+                between peers.</para>
+
+                <para>Buses can be created by any process on-demand. They are
+                self-contained and do not affect each other. Each bus is a
+                closed environment and any connection to the bus will never
+                have any effect to an entity outside of the bus.
+                The creator of a bus has to provide a unique name used to
+                identify the bus. The full list of buses can be queried and
+                specific buses can be looked up by their name. By opening an
+                endpoint of a bus, a process can connect to the bus and
+                initialize a new peer connection. Once set up, it can send and
+                receive messages, query the bus registry and lookup other
+                peers. Additionally, each bus provides a name registry that
+                oversees all well-known names that have been acquired by
+                connected peers. If messages are addressed to well-known names,
+                the name is resolved and the message is sent to the connection
+                that currently has this name acquired. The policy database of
+                each bus defines who is allowed to acquire a particular name,
+                and whether two peers have the permission to talk to each
+                other.</para>
+
+                <para>kdbus provides a pseudo file-system called
+                <emphasis>kdbusfs</emphasis>, which is usually mounted on
+                <filename>/sys/fs/kdbus</filename>. Buses and their endpoints
+                can be accessed as sub-directories and files underneath this
+                mount-point. Any advanced operations are done via
+                <function>ioctl()</function> on files created by
+                <emphasis>kdbusfs</emphasis>. Multiple mount-points of
+                <emphasis>kdbusfs</emphasis> are independent of each other.
+                This allows namespacing of kdbus by mounting a new instance of
+                <emphasis>kdbusfs</emphasis> in a mount-namespace. kdbus calls
+                these domains and each mount has its own kdbus domain, with
+                each bus being linked to exactly one parent domain.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Bus Layout</title>
+
+                <para>A bus
+                (<citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+                provides and defines an environment that peers can connect to
+                for message interchange. A bus is created via the kdbus
+                control interface and can be modified by the bus creator. It
+                applies the policy that control all bus operations. The bus
+                creator itself does not participate as a peer.
+                To establish a peer connection
+                (<citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+                you have to open one of the endpoints
+                (<citerefentry><refentrytitle>kdbus.endpoint</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+                of a bus. Each bus provides a default endpoint, but further
+                endpoints can be created on-demand. Endpoints are used to apply
+                additional policies for all connections on this endpoint. Thus,
+                they provide additional filters to further restrict access of
+                specific connections to the bus.</para>
+
+                <para>Following, you can see an example bus layout:</para>
+<programlisting>
+                                          Bus Creator
+                                               |
+                                               |
+                                            +-----+
+                                            | Bus |
+                                            +-----+
+                                               |
+                    __________________________/ \__________________________
+                   /                                                       \
+                   |                                                       |
+             +----------+                                             +----------+
+             | Endpoint |                                             | Endpoint |
+             +----------+                                             +----------+
+         _________/|\_________                                   _________/|\_________
+        /          |          \                                 /          |          \
+        |          |          |                                 |          |          |
+        |          |          |                                 |          |          |
+   Connection  Connection  Connection                      Connection  Connection  Connection
+</programlisting>
+
+        </refsect1>
+
+        <refsect1>
+                <title>File-system Layout</title>
+
+                <para>The <emphasis>kdbusfs</emphasis>
+                (<citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
+                pseudo file-system provides access to internal kdbus entities,
+                including buses and endpoints. Each time you mount it, a new
+                instance (called <emphasis>domain</emphasis>) will be created
+                which is independent of the other domains.</para>
+
+                <para>Following, you can see an example layout of the
+                <emphasis>kdbusfs</emphasis> file-system:</para>
+<programlisting>
+        /sys/fs/kdbus/                          ; mount-point
+        ├── 0-system                            ; bus directory
+        │   ├── bus                             ; default endpoint
+        │   └── 1017-custom                     ; custom endpoint
+        ├── 1000-user                           ; bus directory
+        │   ├── bus                             ; default endpoint
+        │   ├── 1000-service-A                  ; custom endpoint
+        │   └── 1000-service-B                  ; custom endpoint
+        └── control                             ; control file
+</programlisting>
+
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>kdbus.fs</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.bus</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.connection</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>kdbus.message</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
+                        <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
+                </para>
+        </refsect1>
+
+</refentry>