From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Wed, 18 Mar 2020 15:28:35 +0000 (+0100)
Subject: man: describe sd_bus_default_flush_close()
X-Git-Tag: v246-rc1~726^2~4
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9783b59bf6ad98ff7844aef8f80cf2b69fa57a11;p=thirdparty%2Fsystemd.git

man: describe sd_bus_default_flush_close()
---

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 4e04b413e98..8be77e049fd 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -139,7 +139,7 @@ manpages = [
  ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
  ['sd_bus_call', '3', ['sd_bus_call_async'], ''],
  ['sd_bus_call_method', '3', ['sd_bus_call_method_async'], ''],
- ['sd_bus_close', '3', ['sd_bus_flush'], ''],
+ ['sd_bus_close', '3', ['sd_bus_default_flush_close', 'sd_bus_flush'], ''],
  ['sd_bus_creds_get_pid',
   '3',
   ['sd_bus_creds_get_audit_login_uid',
diff --git a/man/sd_bus_close.xml b/man/sd_bus_close.xml
index d81c593878d..953f16ac343 100644
--- a/man/sd_bus_close.xml
+++ b/man/sd_bus_close.xml
@@ -19,6 +19,7 @@
   <refnamediv>
     <refname>sd_bus_close</refname>
     <refname>sd_bus_flush</refname>
+    <refname>sd_bus_default_flush_close</refname>
 
     <refpurpose>Close and flush a bus connection</refpurpose>
   </refnamediv>
@@ -36,6 +37,11 @@
         <funcdef>int <function>sd_bus_flush</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_bus_default_flush_close</function></funcdef>
+        <paramdef>void</paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -59,6 +65,15 @@
     bus object so that it may be freed. Since these three operations are frequently done together a helper call
     <citerefentry><refentrytitle>sd_bus_flush_close_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> is
     provided that combines them into one.</para>
+
+    <para><function>sd_bus_default_flush_close()</function> is similar to
+    <function>sd_bus_flush_close_unref</function>, but does not take a bus pointer argument and instead
+    iterates over any of the "default" busses opened by
+    <citerefentry><refentrytitle>sd_bus_default</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>,
+    and similar calls. <function>sd_bus_default_flush_close()</function> is particularly useful to clean up
+    any busses opened using those calls before the program exits.</para>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml
index a46b1cb4887..8532c2bf466 100644
--- a/man/sd_bus_default.xml
+++ b/man/sd_bus_default.xml
@@ -313,6 +313,7 @@
       <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>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry project='die-net'><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>