mirror of
https://github.com/systemd/systemd
synced 2024-07-20 17:56:25 +00:00
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.
This commit is contained in:
Lennart Poettering
parent
2306d1778f
commit
cd6d2111c4
|
|
@ -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'],
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
||||
|
|
@ -39,13 +38,6 @@
|
|||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
</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>
|
||||
|
|
@ -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>
|
||||
|
||||
|
|
@ -164,13 +148,6 @@
|
|||
return.</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>
|
||||
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
120
man/sd_bus_set_fd.xml
Normal file
120
man/sd_bus_set_fd.xml
Normal file
|
|
@ -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 <systemd/sd-bus.h></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>
|
||||
Loading…
Reference in a new issue