From 9641fcaf8c057e14fa1c72985e8a670b05e5bbdc Mon Sep 17 00:00:00 2001
From: Sven Eden <yamakuzure@gmx.net>
Date: Thu, 19 Apr 2018 18:37:32 +0200
Subject: Update man page sources to upstream tag v236 variants.

---
 man/sd_bus_add_match.xml | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 2014141ae..4772c738a 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -3,6 +3,8 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
+  SPDX-License-Identifier: LGPL-2.1+
+
   This file is part of systemd.
 
   Copyright 2016 Julian Orth
-- 
cgit v1.2.3


From 822c8205fe497dc8a33619b7d3315193c0b8189c Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 20 Dec 2017 16:31:58 +0100
Subject: man: document all the new APIs we added

---
 man/sd_bus_add_match.xml | 137 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 102 insertions(+), 35 deletions(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 4772c738a..433c2679d 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -45,14 +45,24 @@
 
   <refnamediv>
     <refname>sd_bus_add_match</refname>
+    <refname>sd_bus_add_match_async</refname>
+    <refname>sd_bus_match_signal</refname>
+    <refname>sd_bus_match_signal_async</refname>
 
-    <refpurpose>Add a match rule for message dispatching</refpurpose>
+    <refpurpose>Add a match rule for incoming message dispatching</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
     <funcsynopsis>
       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
 
+      <funcprototype>
+        <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
+        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+        <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_bus_add_match</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -63,57 +73,111 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
-        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+        <funcdef>int <function>sd_bus_add_match_async</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>const char *<parameter>match</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_match_signal</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>const char *<parameter>sender</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const char *<parameter>member</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>void *<parameter>userdata</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_match_signal_async</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
+        <paramdef>const char *<parameter>sender</parameter></paramdef>
+        <paramdef>const char *<parameter>path</parameter></paramdef>
+        <paramdef>const char *<parameter>interface</parameter></paramdef>
+        <paramdef>const char *<parameter>member</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
+        <paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef>
         <paramdef>void *<parameter>userdata</parameter></paramdef>
-        <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
       </funcprototype>
+
     </funcsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
     <title>Description</title>
 
-    <para>
-      <function>sd_bus_add_match()</function> installs a match rule for incoming messages received on the specified bus
-      connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in
-      <parameter>match</parameter> is described in the <ulink
-      url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler
-      function <parameter>callback</parameter> is called for eaching incoming message matching the specified
-      expression, the <parameter>userdata</parameter> parameter is passed as-is to the callback function.
+    <para><function>sd_bus_add_match()</function> installs a match rule for messages received on the specified bus
+    connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in
+    <parameter>match</parameter> is described in the <ulink
+    url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler
+    function <parameter>callback</parameter> is called for eaching incoming message matching the specified expression,
+    the <parameter>userdata</parameter> parameter is passed as-is to the callback function. The match is installed
+    synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added
+    to the broker and waits until the broker confirms the match has been installed successfully.</para>
+
+    <para><function>sd_bus_add_match_async()</function> operates very similar to
+    <function>sd_bus_match_signal()</function>, however it installs the match asynchronously, in a non-blocking
+    fashion: a request is sent to the broker, but the call does not wait for a response. The
+    <parameter>install_callback</parameter> function is called when the response is later received, with the response
+    message from the broker as parameter. If this function is specified as <constant>NULL</constant> a default
+    implementation is used that terminates the bus connection should installing the match fail.</para>
+
+    <para><function>sd_bus_match_signal()</function> is very similar to <function>sd_bus_add_match()</function>, but
+    only matches signals, and instead of a match expression accepts four parameters: <parameter>sender</parameter> (the
+    service name of the sender), <parameter>path</parameter> (the object path of the emitting object),
+    <parameter>interface</parameter> (the interface the signal belongs to), <parameter>member</parameter> (the signal
+    name), from which the match string is internally generated. Optionally, these parameters may be specified as
+    <constant>NULL</constant> in which case the relevant field of incoming signals is not tested.</para>
+
+    <para><function>sd_bus_match_signal_async()</function> is combines the signal matching logic of
+    <function>sd_bus_match_signal()</function> with the asynchronous behaviour of
+    <function>sd_bus_add_match_async()</function>.</para>
+
+    <para>On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be
+    set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again
+    at a later time with
+    <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If specified
+    as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the
+    match cannot be removed independently.</para>
+
+    <para>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should
+    not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
+    <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a
+    new reference.</para>
+
+    <para>If an error occurs during the callback invocation, the callback should return a negative error number
+    (optionally, a more precise error may be returned in <parameter>ret_error</parameter>, as well). If it wants other
+    callbacks that match the same rule to be called, it should return 0. Otherwise it should return a positive integer.
     </para>
 
-    <para>
-      On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be set to
-      a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a
-      later time with
-      <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
-      specified as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the match
-      cannot be removed independently.
-    </para>
+    <para>If the <parameter>bus</parameter> refers to a direct connection (i.e. not a bus connection, as set with
+    <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>) the
+    match is only installed on the client side, and the synchronous and asynchronous functions operate the same.</para>
+  </refsect1>
 
-    <para>
-      The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should not
-      call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> on
-      it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
-      <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create
-      a new reference.
-    </para>
+  <refsect1>
+    <title>Return Value</title>
 
     <para>
-      If an error occurs during the callback invocation, the callback should return a negative error number. If it
-      wants other callbacks that match the same rule to be called, it should return 0. Otherwise it should return a
-      positive integer.
+      On success, <function>sd_bus_add_match()</function> and the other calls return 0 or a positive integer. On
+      failure, they return a negative errno-style error code.
     </para>
   </refsect1>
 
   <refsect1>
-    <title>Return Value</title>
+    <title>Notes</title>
 
-    <para>
-      On success, <function>sd_bus_add_match()</function> returns 0 or a positive integer. On failure, it returns a
-      negative errno-style error code.
-    </para>
+    <para><function>sd_bus_add_match()</function> and the other functions described here are available as a shared
+    library, which can be compiled and linked to with the <constant>libelogind</constant> <citerefentry
+    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
   </refsect1>
 
   <refsect1>
@@ -121,7 +185,10 @@
 
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>
 
-- 
cgit v1.2.3


From 9d1ff89d622fd4d8b3be210996cfa73943d81e03 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Fri, 6 Apr 2018 18:58:55 +0200
Subject: tree-wide: drop license boilerplate

Files which are installed as-is (any .service and other unit files, .conf
files, .policy files, etc), are left as is. My assumption is that SPDX
identifiers are not yet that well known, so it's better to retain the
extended header to avoid any doubt.

I also kept any copyright lines. We can probably remove them, but it'd nice to
obtain explicit acks from all involved authors before doing that.
---
 man/sd_bus_add_match.xml | 13 -------------
 1 file changed, 13 deletions(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 433c2679d..69a755b16 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -8,19 +8,6 @@
   This file is part of systemd.
 
   Copyright 2016 Julian Orth
-
-  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_add_match">
-- 
cgit v1.2.3


From a34becc09a6ec529c2067cd578ec01810b915052 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 30 May 2018 16:28:28 +0200
Subject: man: fix minor typo

---
 man/sd_bus_add_match.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 69a755b16..e8ee2b02b 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -123,7 +123,7 @@
     name), from which the match string is internally generated. Optionally, these parameters may be specified as
     <constant>NULL</constant> in which case the relevant field of incoming signals is not tested.</para>
 
-    <para><function>sd_bus_match_signal_async()</function> is combines the signal matching logic of
+    <para><function>sd_bus_match_signal_async()</function> combines the signal matching logic of
     <function>sd_bus_match_signal()</function> with the asynchronous behaviour of
     <function>sd_bus_add_match_async()</function>.</para>
 
-- 
cgit v1.2.3


From b26856f052f63443124a779c0cafa5a222c762f1 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Wed, 30 May 2018 16:33:12 +0200
Subject: man: document the new sd_bus_slot_set_floating() call

Also extend the memory management description of sd-bus highlighting the
effect of "floating" slot objects a bit.
---
 man/sd_bus_add_match.xml | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index e8ee2b02b..1ca9b4392 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -132,7 +132,9 @@
     at a later time with
     <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If specified
     as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the
-    match cannot be removed independently.</para>
+    match is generally not removed independently. See
+    <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
+    details.</para>
 
     <para>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should
     not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
@@ -175,7 +177,8 @@
       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>
 
-- 
cgit v1.2.3


From dd656b3679e4b5a7ec3534bf8786b022327e080d Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 12 Jun 2018 17:04:27 +0200
Subject: tree-wide: drop 'This file is part of systemd' blurb

This part of the copyright blurb stems from the GPL use recommendations:

https://www.gnu.org/licenses/gpl-howto.en.html

The concept appears to originate in times where version control was per
file, instead of per tree, and was a way to glue the files together.
Ultimately, we nowadays don't live in that world anymore, and this
information is entirely useless anyway, as people are very welcome to
copy these files into any projects they like, and they shouldn't have to
change bits that are part of our copyright header for that.

hence, let's just get rid of this old cruft, and shorten our codebase a
bit.
---
 man/sd_bus_add_match.xml | 2 --
 1 file changed, 2 deletions(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 1ca9b4392..2248abbb1 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -5,8 +5,6 @@
 <!--
   SPDX-License-Identifier: LGPL-2.1+
 
-  This file is part of systemd.
-
   Copyright 2016 Julian Orth
 -->
 
-- 
cgit v1.2.3


From 002c7228dfa839a68591964563e5ef4ded4230a5 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Tue, 12 Jun 2018 19:00:24 +0200
Subject: tree-wide: beautify remaining copyright statements
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Let's unify an beautify our remaining copyright statements, with a
unicode ©. This means our copyright statements are now always formatted
the same way. Yay.
---
 man/sd_bus_add_match.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 2248abbb1..67da9ecf7 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -5,7 +5,7 @@
 <!--
   SPDX-License-Identifier: LGPL-2.1+
 
-  Copyright 2016 Julian Orth
+  Copyright © 2016 Julian Orth
 -->
 
 <refentry id="sd_bus_add_match">
-- 
cgit v1.2.3


From c4bf2a567a48fbc342fe840d821af5da38dd2505 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 14 Jun 2018 12:02:53 +0200
Subject: man: drop unused <authorgroup> tags from man sources

Docbook styles required those to be present, even though the templates that we
use did not show those names anywhere. But something changed semi-recently (I
would suspect docbook templates, but there was only a minor version bump in
recent years, and the changelog does not suggest anything related), and builds
now work without those entries. Let's drop this dead weight.

Tested with F26-F29, debian unstable.

$ perl -i -0pe 's/\s*<authorgroup>.*<.authorgroup>//gms' man/*xml
---
 man/sd_bus_add_match.xml | 8 --------
 1 file changed, 8 deletions(-)

(limited to 'man/sd_bus_add_match.xml')

diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index 67da9ecf7..1cc6157f4 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -13,14 +13,6 @@
   <refentryinfo>
     <title>sd_bus_add_match</title>
     <productname>systemd</productname>
-
-    <authorgroup>
-      <author>
-        <firstname>Julian</firstname>
-        <surname>Orth</surname>
-        <email>ju.orth@gmail.com</email>
-      </author>
-    </authorgroup>
   </refentryinfo>
 
   <refmeta>
-- 
cgit v1.2.3