man: document a batch of bus functions

6 files changed, 969 insertions, 6 deletions

diff --git a/Makefile-man.am b/Makefile-man.am
index 4a0d339ac2..35174cca5f 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -20,7 +20,10 @@ MANPAGES += \
 	man/sd-id128.3 \
 	man/sd-journal.3 \
 	man/sd_booted.3 \
+	man/sd_bus_creds_get_pid.3 \
 	man/sd_bus_message_get_cookie.3 \
+	man/sd_bus_new.3 \
+	man/sd_bus_open_user.3 \
 	man/sd_bus_request_name.3 \
 	man/sd_id128_get_machine.3 \
 	man/sd_id128_randomize.3 \
@@ -135,8 +138,38 @@ MANPAGES_ALIAS += \
 	man/init.1 \
 	man/poweroff.8 \
 	man/reboot.8 \
+	man/sd_bus_creds_get_audit_login_uid.3 \
+	man/sd_bus_creds_get_audit_session_id.3 \
+	man/sd_bus_creds_get_cgroup.3 \
+	man/sd_bus_creds_get_cmdline.3 \
+	man/sd_bus_creds_get_comm.3 \
+	man/sd_bus_creds_get_exe.3 \
+	man/sd_bus_creds_get_gid.3 \
+	man/sd_bus_creds_get_owner_uid.3 \
+	man/sd_bus_creds_get_pid_starttime.3 \
+	man/sd_bus_creds_get_selinux_context.3 \
+	man/sd_bus_creds_get_session.3 \
+	man/sd_bus_creds_get_slice.3 \
+	man/sd_bus_creds_get_tid.3 \
+	man/sd_bus_creds_get_tid_comm.3 \
+	man/sd_bus_creds_get_uid.3 \
+	man/sd_bus_creds_get_unique_name.3 \
+	man/sd_bus_creds_get_unit.3 \
+	man/sd_bus_creds_get_user_unit.3 \
+	man/sd_bus_creds_get_well_known_names.3 \
+	man/sd_bus_creds_has_bounding_cap.3 \
+	man/sd_bus_creds_has_effective_cap.3 \
+	man/sd_bus_creds_has_inheritable_cap.3 \
+	man/sd_bus_creds_has_permitted_cap.3 \
+	man/sd_bus_default_system.3 \
+	man/sd_bus_default_user.3 \
 	man/sd_bus_message_get_reply_cookie.3 \
+	man/sd_bus_open_system.3 \
+	man/sd_bus_open_system_container.3 \
+	man/sd_bus_open_system_remote.3 \
+	man/sd_bus_ref.3 \
 	man/sd_bus_release_name.3 \
+	man/sd_bus_unref.3 \
 	man/sd_id128_equal.3 \
 	man/sd_id128_from_string.3 \
 	man/sd_id128_get_boot.3 \
@@ -239,8 +272,38 @@ man/SD_WARNING.3: man/sd-daemon.3
 man/init.1: man/systemd.1
 man/poweroff.8: man/halt.8
 man/reboot.8: man/halt.8
+man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_audit_session_id.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_cgroup.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_cmdline.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_comm.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_exe.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_gid.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_owner_uid.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_pid_starttime.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_selinux_context.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_session.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_slice.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_tid.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_tid_comm.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_uid.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_unique_name.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_unit.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_user_unit.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_get_well_known_names.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_has_bounding_cap.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_has_effective_cap.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_has_inheritable_cap.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_creds_has_permitted_cap.3: man/sd_bus_creds_get_pid.3
+man/sd_bus_default_system.3: man/sd_bus_open_user.3
+man/sd_bus_default_user.3: man/sd_bus_open_user.3
 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3
+man/sd_bus_open_system.3: man/sd_bus_open_user.3
+man/sd_bus_open_system_container.3: man/sd_bus_open_user.3
+man/sd_bus_open_system_remote.3: man/sd_bus_open_user.3
+man/sd_bus_ref.3: man/sd_bus_new.3
 man/sd_bus_release_name.3: man/sd_bus_request_name.3
+man/sd_bus_unref.3: man/sd_bus_new.3
 man/sd_id128_equal.3: man/sd-id128.3
 man/sd_id128_from_string.3: man/sd_id128_to_string.3
 man/sd_id128_get_boot.3: man/sd_id128_get_machine.3
@@ -399,12 +462,102 @@ man/poweroff.html: man/halt.html
 man/reboot.html: man/halt.html
 	$(html-alias)
 
+man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_audit_session_id.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_cgroup.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_cmdline.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_comm.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_exe.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_gid.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_owner_uid.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_pid_starttime.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_selinux_context.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_session.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_slice.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_tid.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_tid_comm.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_uid.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_unique_name.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_unit.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_user_unit.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_get_well_known_names.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_has_bounding_cap.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_has_effective_cap.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_has_inheritable_cap.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_creds_has_permitted_cap.html: man/sd_bus_creds_get_pid.html
+	$(html-alias)
+
+man/sd_bus_default_system.html: man/sd_bus_open_user.html
+	$(html-alias)
+
+man/sd_bus_default_user.html: man/sd_bus_open_user.html
+	$(html-alias)
+
 man/sd_bus_message_get_reply_cookie.html: man/sd_bus_message_get_cookie.html
 	$(html-alias)
 
+man/sd_bus_open_system.html: man/sd_bus_open_user.html
+	$(html-alias)
+
+man/sd_bus_open_system_container.html: man/sd_bus_open_user.html
+	$(html-alias)
+
+man/sd_bus_open_system_remote.html: man/sd_bus_open_user.html
+	$(html-alias)
+
+man/sd_bus_ref.html: man/sd_bus_new.html
+	$(html-alias)
+
 man/sd_bus_release_name.html: man/sd_bus_request_name.html
 	$(html-alias)
 
+man/sd_bus_unref.html: man/sd_bus_new.html
+	$(html-alias)
+
 man/sd_id128_equal.html: man/sd-id128.html
 	$(html-alias)
 
@@ -1112,7 +1265,10 @@ EXTRA_DIST += \
 	man/sd-login.xml \
 	man/sd-readahead.xml \
 	man/sd_booted.xml \
+	man/sd_bus_creds_get_pid.xml \
 	man/sd_bus_message_get_cookie.xml \
+	man/sd_bus_new.xml \
+	man/sd_bus_open_user.xml \
 	man/sd_bus_request_name.xml \
 	man/sd_get_seats.xml \
 	man/sd_id128_get_machine.xml \
diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml
new file mode 100644
index 0000000000..9de5001d49
--- /dev/null
+++ b/man/sd_bus_creds_get_pid.xml
@@ -0,0 +1,445 @@
+<?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 Zbigniew Jędrzejewski-Szmek
+
+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="sd_bus_creds_get_pid">
+
+  <refentryinfo>
+    <title>sd_bus_creds_get_pid</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>A monkey with a typewriter</contrib>
+        <firstname>Zbigniew</firstname>
+        <surname>Jędrzejewski-Szmek</surname>
+        <email>zbyszek@in.waw.pl</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_creds_get_pid</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_creds_get_pid</refname>
+    <refname>sd_bus_creds_get_pid_starttime</refname>
+    <refname>sd_bus_creds_get_tid</refname>
+    <refname>sd_bus_creds_get_uid</refname>
+    <refname>sd_bus_creds_get_gid</refname>
+    <refname>sd_bus_creds_get_comm</refname>
+    <refname>sd_bus_creds_get_tid_comm</refname>
+    <refname>sd_bus_creds_get_exe</refname>
+    <refname>sd_bus_creds_get_cmdline</refname>
+    <refname>sd_bus_creds_get_cgroup</refname>
+    <refname>sd_bus_creds_get_unit</refname>
+    <refname>sd_bus_creds_get_user_unit</refname>
+    <refname>sd_bus_creds_get_slice</refname>
+    <refname>sd_bus_creds_get_session</refname>
+    <refname>sd_bus_creds_get_owner_uid</refname>
+    <refname>sd_bus_creds_has_effective_cap</refname>
+    <refname>sd_bus_creds_has_permitted_cap</refname>
+    <refname>sd_bus_creds_has_inheritable_cap</refname>
+    <refname>sd_bus_creds_has_bounding_cap</refname>
+    <refname>sd_bus_creds_get_selinux_context</refname>
+    <refname>sd_bus_creds_get_audit_session_id</refname>
+    <refname>sd_bus_creds_get_audit_login_uid</refname>
+    <refname>sd_bus_creds_get_unique_name</refname>
+    <refname>sd_bus_creds_get_well_known_names</refname>
+
+    <refpurpose>Retrieve fields from a credentials object</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>pid_t *<parameter>pid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_pid_starttime</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>pid_t *<parameter>tid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>uid_t *<parameter>uid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>gid_t *<parameter>gid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>comm</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>comm</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>exe</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>char ***<parameter>cmdline</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>cgroup</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>unit</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>unit</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>slice</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_session</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>slice</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>uid_t *<parameter>uid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>int <parameter>capability</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>int <parameter>capability</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>int <parameter>capability</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>int <parameter>capability</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>context</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>uid_t *<parameter>loginuid</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>const char **<parameter>name</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef>
+        <paramdef>sd_bus_creds* <parameter>c</parameter></paramdef>
+        <paramdef>char ***<parameter>name</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>Those functions return information from an
+    <parameter>sd_bus_creds</parameter> object. It may be created with
+    <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    in which case it will describe the specified process, or it may be
+    created by
+    <citerefentry><refentrytitle>sd_bus_get_peer_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+    in which case it will describe the process at the other endpoint
+    of a connection.
+    </para>
+
+    <para><function>sd_bus_creds_get_pid</function> will retrieve the
+    PID (process identifier).</para>
+
+    <para><function>sd_bus_creds_get_pid_starttime</function> will
+    retrieve the time since the start of the epoch in microseconds
+    since the process was started.</para>
+
+    <para><function>sd_bus_creds_get_tid</function> will retrieve the
+    TID (thread identifier).</para>
+
+    <para><function>sd_bus_creds_get_uid</function> will retrieve the
+    UID (user identifier).</para>
+
+    <para><function>sd_bus_creds_get_gid</function> will retrieve the
+    GID (group identifier).</para>
+
+    <para><function>sd_bus_creds_get_comm</function> will retrieve the
+    comm field (name of the executable, as stored in
+    <filename>/proc/<replaceable>pid</replaceable>/comm</filename>).
+    </para>
+
+    <para><function>sd_bus_creds_get_tid_comm</function> will retrieve
+    the comm field of the thread (as stored in
+    <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>).
+    </para>
+
+    <para><function>sd_bus_creds_get_exe</function> will retrieve the
+    path to the program (as stored in the
+    <filename>/proc/<replaceable>pid</replaceable>/exe</filename>
+    link, but with <literal> (deleted)</literal> suffix removed).
+    </para>
+
+    <para><function>sd_bus_creds_get_cmdline</function> will retrieve
+    an array of command-line arguments (as stored in
+    <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>).
+    </para>
+
+    <para><function>sd_bus_creds_get_cgroup</function> will retrieve
+    the cgroup path. See <ulink
+    url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.
+    </para>
+
+    <para><function>sd_bus_creds_get_unit</function> will retrieve the
+    systemd unit name (in the system instance of systemd) that the
+    process is part of. See
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_creds_get_user_unit</function> will
+    retrieve the systemd unit name (in the user instance of systemd)
+    that the process is part of. See
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_creds_get_slice</function> will retrieve
+    the systemd slice (a unit in the system instance of systemd) that
+    the process is part of. See
+    <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_creds_get_session</function> will retrieve
+    the logind session that the process is part of. See
+    <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_creds_get_owner_uid</function> will retrieve
+    the UID (user identifier) of the user who owns the slice
+    that the process is part of. See
+    <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    <!-- and
+    <citerefentry><refentrytitle>systemd-user-sessions.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> -->.
+    </para>
+
+    <para><function>sd_bus_creds_has_effective_cap</function> will
+    check whether all of the capabilities specified by
+    <parameter>capability</parameter> were set in the effective
+    capabilities mask. A positive return value means that they were
+    set, zero means that they were not set, and a negative return
+    value signifies an error. See
+    <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    and <varname>Capabilities=</varname> and
+    <varname>CapabilityBoundingSet=</varname> settings in
+    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <para><function>sd_bus_creds_has_permitted_cap</function> is
+    similar to <function>sd_bus_creds_has_effective_cap</function>,
+    but will check the permitted capabilities mask.</para>
+
+    <para><function>sd_bus_creds_has_inheritable_cap</function> is
+    similar to <function>sd_bus_creds_has_effective_cap</function>,
+    but will check the inheritable capabilities mask.</para>
+
+    <para><function>sd_bus_creds_has_bounding_cap</function> is
+    similar to <function>sd_bus_creds_has_effective_cap</function>,
+    but will check the bounding capabilities mask.</para>
+
+    <para><function>sd_bus_creds_get_selinux_context</function> will
+    retrieve the SELinux context of the process.</para>
+
+    <para><function>sd_bus_creds_get_audit_session_id</function> will
+    retrieve the audit session identifier of the process.</para>
+
+    <para><function>sd_bus_creds_get_audit_login_uid</function> will
+    retrieve the audit user login identifier (the identifier of the
+    user who is "responsible" for the session).</para>
+
+    <para><function>sd_bus_creds_get_unique_name</function> will
+    retrieve the D-Bus unique name. See <ulink
+    url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
+    D-Bus specification</ulink>.</para>
+
+    <para><function>sd_bus_creds_get_well_known_names</function> will
+    retrieve the set of D-Bus well-known names. See <ulink
+    url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The
+    D-Bus specification</ulink>.</para>
+
+    <para>All functions that take a <parameter>const
+    char**</parameter> parameter will store the answer there as an
+    address of a NUL-terminated string. It will be valid as long as
+    <parameter>c</parameter> remains valid, and should not be freed or
+    modified by the caller.</para>
+
+    <para>All functions that take a <parameter>char***</parameter>
+    parameter will store the answer there as an address of a an array
+    of strings. Each invidividual string is NUL-terminated, and the
+    array is NULL-terminated as a whole. It will be valid as long as
+    <parameter>c</parameter> remains valid, and should not be freed or
+    modified by the caller.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these calls return 0 or a positive integer. On
+    failure, these calls return a negative errno-style error code.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>-ENODATA</varname></term>
+
+        <listitem><para>Given field is not available in
+        <parameter>c</parameter>.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>-ENOENT</varname></term>
+
+        <listitem><para>Given field is not specified for the sender.
+        This will be returned by <function>sd_bus_get_unit</function>,
+        <function>sd_bus_get_user_unit</function>,
+        <function>sd_bus_get_slice</function>,
+        <function>sd_bus_get_session</function>, and
+        <function>sd_bus_get_owner_uid</function> if the sender is not
+        part of a systemd system unit, systemd user unit, systemd
+        slice, logind session, or a systemd user session.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>-EINVAL</varname></term>
+
+        <listitem><para>Specified pointer parameter is <constant>NULL</constant>.
+        </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>-ENOMEM</varname></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para><function>sd_bus_open_user()</function> and other functions
+    described here are available as a shared library, which can be
+    compiled and linked to with the
+    <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd.journald-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml
new file mode 100644
index 0000000000..1931424b86
--- /dev/null
+++ b/man/sd_bus_new.xml
@@ -0,0 +1,145 @@
+<?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 Zbigniew Jędrzejewski-Szmek
+
+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="sd_bus_new">
+
+  <refentryinfo>
+    <title>sd_bus_new</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>A monkey with a typewriter</contrib>
+        <firstname>Zbigniew</firstname>
+        <surname>Jędrzejewski-Szmek</surname>
+        <email>zbyszek@in.waw.pl</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_new</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_new</refname>
+    <refname>sd_bus_ref</refname>
+    <refname>sd_bus_unref</refname>
+
+    <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_new</function></funcdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>sd_bus* <function>sd_bus_ref</function></funcdef>
+        <paramdef>sd_bus* <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>sd_bus* <function>sd_bus_unref</function></funcdef>
+        <paramdef>sd_bus* <parameter>bus</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_new()</function> creates a new bus
+    object. This object is reference counted, and will be destroyed
+    when all references are gone. Initially, the caller of this
+    function owns the sole reference.</para>
+
+    <para><function>sd_bus_ref()</function> creates a new reference to
+    <parameter>bus</parameter>. This bus object will not be destroyed
+    until <function>sd_bus_unref()</function> has been called as many
+    times plus once more. Once the reference count has dropped to
+    zero, <parameter>bus</parameter> cannot be used anymore, so
+    further calls to <function>sd_bus_ref()</function> or
+    <function>sd_bus_unref()</function> are illegal.</para>
+
+    <para><function>sd_bus_unref()</function> destroyes a reference to
+    <parameter>bus</parameter>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_bus_new()</function> returns 0 or a
+    positive integer. On failure, it returns a negative errno-style
+    error code.</para>
+
+    <para><function>sd_bus_ref</function> always returns the argument.
+    </para>
+
+    <para><function>sd_bus_unref</function> always returns
+    <constant>NULL</constant>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>-ENOMEM</varname></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para><function>sd_bus_new()</function> and other functions
+    described here are available as a shared library, which can be
+    compiled and linked to with the
+    <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sd_bus_open_user.xml b/man/sd_bus_open_user.xml
new file mode 100644
index 0000000000..62b856993d
--- /dev/null
+++ b/man/sd_bus_open_user.xml
@@ -0,0 +1,217 @@
+<?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 Zbigniew Jędrzejewski-Szmek
+
+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="sd_bus_open_user">
+
+  <refentryinfo>
+    <title>sd_bus_open_user</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>A monkey with a typewriter</contrib>
+        <firstname>Zbigniew</firstname>
+        <surname>Jędrzejewski-Szmek</surname>
+        <email>zbyszek@in.waw.pl</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_open_user</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_open_user</refname>
+    <refname>sd_bus_open_system</refname>
+    <refname>sd_bus_open_system_remote</refname>
+    <refname>sd_bus_open_system_container</refname>
+
+    <refname>sd_bus_default_user</refname>
+    <refname>sd_bus_default_system</refname>
+
+    <refpurpose>Open a connection to the system or user bus</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_user</function></funcdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_system</function></funcdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
+        <paramdef>const char *<parameter>host</parameter></paramdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_open_system_container</function></funcdef>
+        <paramdef>const char *<parameter>machine</parameter></paramdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_default_user</function></funcdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_default_system</function></funcdef>
+        <paramdef>sd_bus** <parameter>bus</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_open_user()</function> creates a new bus
+    object and opens a connection to the the user bus.
+    <function>sd_bus_open_system()</function> does the same, but
+    connects to the system bus.</para>
+
+    <para>If <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
+    variable is set
+    (c.f. <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+    it will be used as the address of the user bus. This variable can
+    contain multiple addresses separated by <literal>;</literal>. If
+    this variable is not set, a suitable default for the default user
+    D-Bus instance will be used.</para>
+
+    <para>If <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment
+    variable is set, it will be used as the address of the system
+    bus. This variable uses the same syntax as
+    <varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is
+    not set, a suitable default for the default system D-Bus instance
+    will be used.</para>
+
+    <para><function>sd_bus_open_system_remote()</function> connects to
+    the system bus on the specified <parameter>host</parameter> using
+    SSH. <parameter>host</parameter> consists of an optional user name
+    followed by the <literal>@</literal> symbol, and the hostname.
+    </para>
+
+    <para><function>sd_bus_open_system_remote()</function> connects to
+    the system bus in the specified <parameter>machine</parameter>,
+    where <parameter>machine</parameter> is the name of a container.
+    See
+    <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    for more information about "machines".</para>
+
+    <para><function>sd_bus_default_user()</function> returns a bus
+    object connected to the user bus. This bus object is shared
+    per-thread. It is created on the first invocation of
+    <function>sd_bus_default_user()</function>, and subsequent
+    invocations returns a reference to the same object.</para>
+
+    <para><function>sd_bus_default_system()</function> is similar to
+    <function>sd_bus_default_user()</function>, but connects to the
+    system bus.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these calls return 0 or a positive
+    integer. On failure, these calls return a negative
+    errno-style error code.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Reference ownership</title>
+    <para>Functions <function>sd_bus_open_user()</function>,
+    <function>sd_bus_open_system()</function>,
+    <function>sd_bus_open_system_remote()</function>, and
+    <function>sd_bus_open_system_machine()</function> return a new
+    object and the caller owns the sole reference. When not needed
+    anymore, this reference should be destroyed with
+    <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+    </para>
+
+    <para>Functions <function>sd_bus_default_user()</function> and
+    <function>sd_bus_default_system()</function> do not create a new
+    reference.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><varname>-EINVAL</varname></term>
+
+        <listitem><para>Specified parameter is invalid
+        (<constant>NULL</constant> in case of output
+        parameters).</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>-ENOMEM</varname></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+
+      <para>In addition, any further connection-related errors may be
+      by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para><function>sd_bus_open_user()</function> and other functions
+    described here are available as a shared library, which can be
+    compiled and linked to with the
+    <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/src/libsystemd-bus/sd-bus.c b/src/libsystemd-bus/sd-bus.c
index 61dc0e56a8..c2f77a990f 100644
--- a/src/libsystemd-bus/sd-bus.c
+++ b/src/libsystemd-bus/sd-bus.c
@@ -1234,7 +1234,7 @@ _public_ void sd_bus_close(sd_bus *bus) {
 
         /* We'll leave the fd open in case this is a kernel bus, since
          * there might still be memblocks around that reference this
-         * bus, and they might need to invoke the * KDBUS_CMD_FREE
+         * bus, and they might need to invoke the KDBUS_CMD_FREE
          * ioctl on the fd when they are freed. */
 }
 
diff --git a/src/systemd/sd-bus.h b/src/systemd/sd-bus.h
index b3b92ad612..1134b58437 100644
--- a/src/systemd/sd-bus.h
+++ b/src/systemd/sd-bus.h
@@ -286,11 +286,11 @@ int sd_bus_creds_get_pid_starttime(sd_bus_creds *c, uint64_t *usec);
 int sd_bus_creds_get_tid(sd_bus_creds *c, pid_t *tid);
 int sd_bus_creds_get_uid(sd_bus_creds *c, uid_t *uid);
 int sd_bus_creds_get_gid(sd_bus_creds *c, gid_t *gid);
-int sd_bus_creds_get_comm(sd_bus_creds *c, const char **r);
-int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **r);
-int sd_bus_creds_get_exe(sd_bus_creds *c, const char **r);
+int sd_bus_creds_get_comm(sd_bus_creds *c, const char **comm);
+int sd_bus_creds_get_tid_comm(sd_bus_creds *c, const char **comm);
+int sd_bus_creds_get_exe(sd_bus_creds *c, const char **exe);
 int sd_bus_creds_get_cmdline(sd_bus_creds *c, char ***cmdline);
-int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **r);
+int sd_bus_creds_get_cgroup(sd_bus_creds *c, const char **cgroup);
 int sd_bus_creds_get_unit(sd_bus_creds *c, const char **unit);
 int sd_bus_creds_get_user_unit(sd_bus_creds *c, const char **unit);
 int sd_bus_creds_get_slice(sd_bus_creds *c, const char **slice);
@@ -300,7 +300,7 @@ int sd_bus_creds_has_effective_cap(sd_bus_creds *c, int capability);
 int sd_bus_creds_has_permitted_cap(sd_bus_creds *c, int capability);
 int sd_bus_creds_has_inheritable_cap(sd_bus_creds *c, int capability);
 int sd_bus_creds_has_bounding_cap(sd_bus_creds *c, int capability);
-int sd_bus_creds_get_selinux_context(sd_bus_creds *c, const char **r);
+int sd_bus_creds_get_selinux_context(sd_bus_creds *c, const char **context);
 int sd_bus_creds_get_audit_session_id(sd_bus_creds *c, uint32_t *sessionid);
 int sd_bus_creds_get_audit_login_uid(sd_bus_creds *c, uid_t *loginuid);
 int sd_bus_creds_get_unique_name(sd_bus_creds *c, const char **name);