From 0eb5b641c5f1d5160cd87cca016755dc45f15b33 Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan.j.demeyer@gmail.com>
Date: Tue, 21 Apr 2020 19:33:25 +0200
Subject: [PATCH] sd-bus: Add sd_bus_set/is_monitor docs

---
 man/rules/meson.build     |  4 +++-
 man/sd-bus.xml            |  2 ++
 man/sd_bus_set_server.xml | 39 +++++++++++++++++++++++++++++++++------
 3 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 222c0d2919..656caece76 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -407,8 +407,10 @@ manpages = [
   '3',
   ['sd_bus_get_bus_id',
    'sd_bus_is_bus_client',
+   'sd_bus_is_monitor',
    'sd_bus_is_server',
-   'sd_bus_set_bus_client'],
+   'sd_bus_set_bus_client',
+   'sd_bus_set_monitor'],
   ''],
  ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
  ['sd_bus_slot_get_bus',
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index 9918e0c737..c576578cf2 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -84,6 +84,7 @@
 <citerefentry><refentrytitle>sd_bus_get_scope</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_tid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_get_unique_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_is_monitor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_is_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_is_server</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
@@ -131,6 +132,7 @@
 <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_exit_on_disconnect</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_method_call_timeout</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_set_monitor</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_property</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_propertyv</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 <citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
diff --git a/man/sd_bus_set_server.xml b/man/sd_bus_set_server.xml
index 309a535f51..625dfd4468 100644
--- a/man/sd_bus_set_server.xml
+++ b/man/sd_bus_set_server.xml
@@ -22,8 +22,10 @@
     <refname>sd_bus_get_bus_id</refname>
     <refname>sd_bus_set_bus_client</refname>
     <refname>sd_bus_is_bus_client</refname>
+    <refname>sd_bus_set_monitor</refname>
+    <refname>sd_bus_is_monitor</refname>
 
-    <refpurpose>Configure direct connection mode for a bus object</refpurpose>
+    <refpurpose>Configure connection mode for a bus object</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -58,6 +60,17 @@
         <funcdef>int <function>sd_bus_is_bus_client</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_set_monitor</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>int <parameter>b</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_is_monitor</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -98,18 +111,32 @@
 
     <para><function>sd_bus_is_bus_client()</function> returns whether the client mode is enabled/disabled for
     the given bus object.</para>
+
+    <para><function>sd_bus_set_monitor()</function> configures the bus object as a D-Bus monitor object.
+    <parameter>b</parameter> enables/disables the monitor mode. If zero, the monitor mode is disabled. If
+    non-zero, the monitor mode is enabled. When the monitor mode is enabled, no messages may be sent via the
+    bus object and it may not expose any objects on the bus. To start monitoring messages, call the
+    <function>org.freedesktop.DBus.Monitoring.BecomeMonitor</function> method of the D-Bus daemon and pass
+    a list of matches indicating which messages to intercept. See
+    <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor">
+    The D-Bus specification</ulink> for more information.</para>
+
+    <para><function>sd_bus_is_monitor()</function> returns whether the monitor mode is enabled/disabled for
+    the given bus object.</para>
+
   </refsect1>
 
   <refsect1>
     <title>Return Value</title>
 
     <para>On success, <function>sd_bus_set_server()</function>,
-    <function>sd_bus_get_bus_id()</function> and <function>sd_bus_set_bus_client()</function> return a
-    non-negative integer. On failure, they return a negative errno-style error code.</para>
+    <function>sd_bus_get_bus_id()</function>, <function>sd_bus_set_bus_client()</function> and
+    <function>sd_bus_set_monitor()</function> return a non-negative integer. On failure, they return a
+    negative errno-style error code.</para>
 
-    <para><function>sd_bus_is_server()</function> and <function>sd_bus_is_bus_client()</function> return a
-    positive integer when the server or client mode is enabled, respectively. Otherwise, they return zero.
-    </para>
+    <para><function>sd_bus_is_server()</function>, <function>sd_bus_is_bus_client()</function> and
+    <function>sd_bus_is_monitor()</function> return a positive integer when the server or client mode is
+    enabled, respectively. Otherwise, they return zero.</para>
 
     <refsect2>
       <title>Errors</title>