man: split out sd_bus_set_fd() man page from sd_bus_get_fd()

sd_bus_get_fd() and related calls are useful for integrating a bus
connection into arbitrary event loops. But sd_bus_set_fd() is quite a
different beast, it's for using D-Bus over pre-initialized sockets or
pairs of fifos or stuff, i.e. very advanced stuff.

Let's split this man page in two, in order not to confuse things
needlessly.

And while we are at it, let's slightly extend the documentation.

3 files changed, 123 insertions, 27 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 763863afef..a48158f562 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -269,10 +269,7 @@ manpages = [
    'sd_bus_get_current_slot',
    'sd_bus_get_current_userdata'],
   ''],
- ['sd_bus_get_fd',
-  '3',
-  ['sd_bus_get_events', 'sd_bus_get_timeout', 'sd_bus_set_fd'],
-  ''],
+ ['sd_bus_get_fd', '3', ['sd_bus_get_events', 'sd_bus_get_timeout'], ''],
  ['sd_bus_get_n_queued_read', '3', ['sd_bus_get_n_queued_write'], ''],
  ['sd_bus_get_name_creds', '3', ['sd_bus_get_owner_creds'], ''],
  ['sd_bus_get_name_machine_id', '3', [], ''],
@@ -430,6 +427,7 @@ manpages = [
    'sd_bus_set_trusted'],
   ''],
  ['sd_bus_set_exit_on_disconnect', '3', ['sd_bus_get_exit_on_disconnect'], ''],
+ ['sd_bus_set_fd', '3', [], ''],
  ['sd_bus_set_method_call_timeout',
   '3',
   ['sd_bus_get_method_call_timeout'],
diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml
index 7297db316f..2c0ec8fc05 100644
--- a/man/sd_bus_get_fd.xml
+++ b/man/sd_bus_get_fd.xml
@@ -22,7 +22,6 @@
 
   <refnamediv>
     <refname>sd_bus_get_fd</refname>
-    <refname>sd_bus_set_fd</refname>
     <refname>sd_bus_get_events</refname>
     <refname>sd_bus_get_timeout</refname>
 
@@ -40,13 +39,6 @@
       </funcprototype>
 
       <funcprototype>
-        <funcdef>int <function>sd_bus_set_fd</function></funcdef>
-        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
-        <paramdef>int <parameter>input_fd</parameter></paramdef>
-        <paramdef>int <parameter>output_fd</parameter></paramdef>
-      </funcprototype>
-
-      <funcprototype>
         <funcdef>int <function>sd_bus_get_events</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
@@ -69,11 +61,6 @@
     object was configured with the <function>sd_bus_set_fd()</function> function, then the
     <parameter>input_fd</parameter> file descriptor used in that call is returned.</para>
 
-    <para><function>sd_bus_set_fd()</function> sets the file descriptors used to communicate from a
-    message bus object. Both <parameter>input_fd</parameter> and <parameter>output_fd</parameter>
-    must be valid file descriptors. The same file descriptor may be used as both the input and the
-    output file descriptor. This function must be called before the bus is started.</para>
-
     <para><function>sd_bus_get_events()</function> returns the I/O events to wait for, suitable for
     passing to <function>poll()</function> or a similar call. Returns a combination of
     <constant>POLLIN</constant>, <constant>POLLOUT</constant>, … events, or negative on error.
@@ -122,9 +109,6 @@
     <para>On success, <function>sd_bus_get_fd()</function> returns the file descriptor used for
     communication. On failure, it returns a negative errno-style error code.</para>
 
-    <para>On success, <function>sd_bus_set_fd()</function> returns a non-negative integer. On
-    failure, it returns a negative errno-style error code.</para>
-
     <para>On success, <function>sd_bus_get_events()</function> returns the I/O event mask to use for
     I/O event watching. On failure, it returns a negative errno-style error code.</para>
 
@@ -165,13 +149,6 @@
         </varlistentry>
 
         <varlistentry>
-          <term><constant>-EBADF</constant></term>
-
-          <listitem><para>An invalid file descriptor was passed to
-          <function>sd_bus_set_fd()</function>.</para></listitem>
-        </varlistentry>
-
-        <varlistentry>
           <term><constant>-ENOPKG</constant></term>
 
           <listitem><para>The bus cannot be resolved.</para></listitem>
@@ -191,6 +168,7 @@
       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     </para>
   </refsect1>
diff --git a/man/sd_bus_set_fd.xml b/man/sd_bus_set_fd.xml
new file mode 100644
index 0000000000..3860ab06cd
--- /dev/null
+++ b/man/sd_bus_set_fd.xml
@@ -0,0 +1,120 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  SPDX-License-Identifier: LGPL-2.1-or-later
+
+  Copyright © 2016 Julian Orth
+-->
+
+<refentry id="sd_bus_set_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_bus_set_fd</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_set_fd</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_set_fd</refname>
+
+    <refpurpose>Set the file descriptors to use for bus communication</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_set_fd</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>int <parameter>input_fd</parameter></paramdef>
+        <paramdef>int <parameter>output_fd</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_set_fd()</function> sets the file descriptors used to communicate by a bus
+    connection object. Both <parameter>input_fd</parameter> and <parameter>output_fd</parameter> must be
+    valid file descriptors, referring to stream-based file objects (e.g. a stream socket, a pair of pipes or
+    FIFOs, or a even a TTY device). <parameter>input_fd</parameter> must be readable, and
+    <parameter>output_fd</parameter> must be writable. The same file descriptor may be used (and typically is
+    used) as both the input and the output file descriptor. This function must be called before the bus
+    connection is started via
+    <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+    <para>The bus connection object will take possession of the passed file descriptors and will close them
+    automatically when it is freed. Use
+    <citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    to turn off this behaviour.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, <function>sd_bus_set_fd()</function> returns a non-negative integer. On
+    failure, it returns a negative errno-style error code.</para>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>An invalid bus object was passed.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ECHILD</constant></term>
+
+          <listitem><para>The bus connection was allocated in a parent process and is being reused
+          in a child process after <function>fork()</function>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EBADF</constant></term>
+
+          <listitem><para>An invalid file descriptor was passed to
+          <function>sd_bus_set_fd()</function>.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-ENOPKG</constant></term>
+
+          <listitem><para>The bus cannot be resolved.</para></listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><constant>-EPERM</constant></term>
+
+          <listitem><para>The bus connection has aleady been started.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <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_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>