mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-12 19:53:55 +08:00
Code Issues Packages Projects Releases Wiki Activity
c892816ceb
systemd/man/sd_bus_process.xml

151 lines
6.7 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 05:15:39 +08:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
<!--
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
SPDX-License-Identifier: LGPL-2.1-or-later
Add SPDX license identifiers to man pages
2017-11-19 00:22:32 +08:00
tree-wide: beautify remaining copyright statements 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.
2018-06-13 01:00:24 +08:00
Copyright © 2016 Julian Orth
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
-->
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
<refentry id="sd_bus_process" xmlns:xi="http://www.w3.org/2001/XInclude">
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
<refentryinfo>
<title>sd_bus_process</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_process</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_process</refname>
<refpurpose>Drive the connection</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_process</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
<paramdef>sd_bus_message **<parameter>ret</parameter></paramdef>
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man/sd_bus_process: fix confusion about "synchronous" An event loop is not "synchronous". So we shouldn't say that the client must "synchrounusly poll" if we recommend an event loop. Let's just say it should poll, and say that "sd_bus_wait()" is blocking, which is clearer and more correct than "synchronous".
2023-11-16 18:12:00 +08:00
<para><function>sd_bus_process()</function> drives the connection between the client and the message bus.
That is, it handles connecting, authentication, and processing of messages. When invoked, pending I/O
work is executed, and queued incoming messages are dispatched to registered callbacks. Each time it is
invoked a single operation is executed. It returns zero when no operations were pending and positive if a
message was processed. When zero is returned the caller should poll for I/O events before calling into
<function>sd_bus_process()</function> again. For that either use the simple, blocking
<citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> call, or
hook up the bus connection object to an external or manual event loop using
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
</para>
man: document that sd_bus_process() only returns otherwise unhandled messages in *ret_message
2024-09-12 20:13:22 +08:00
<para><function>sd_bus_process()</function> processes at most one incoming message per call. If the
parameter <parameter>ret</parameter> is not <constant>NULL</constant> and the call processed a message,
<parameter>*ret</parameter> is set to this message. The caller owns a reference to this message and
should call
<citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
when the message is no longer needed. If <parameter>ret</parameter> is not <constant>NULL</constant> and
progress was made, but no message was processed, <parameter>*ret</parameter> is set to
<constant>NULL</constant>. Note that only messages not already handled by the various types of registered
message handlers (i.e. by filters registered via
<citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
object handlers registered via
<citerefentry><refentrytitle>sd_bus_add_object</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
matches registered via
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
and related) will be returned through this parameter. Also note that if such a message handler returns a
zero return value (as opposed to some value &gt; 0) an incoming message will not be considered handled,
and be passed to other suitable handlers (until one returns &gt; > 0), or returned by
<function>sd_bus_process()</function> (in case none returns &gt; 0).</para>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
tree-wide: fix "a the" or "the a"
2020-11-13 15:19:49 +08:00
<para>If the bus object is connected to an
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop (with
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it is not
necessary to call <function>sd_bus_process()</function> directly as it is invoked automatically when
necessary.</para>
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
</refsect1>
<refsect1>
<title>Return Value</title>
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<para>If progress was made, a positive integer is returned. If no progress was made, 0 is returned. If an
error occurs, a negative <varname>errno</varname>-style error code is returned.</para>
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<refsect2>
<title>Errors</title>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<para>Returned errors may indicate the following problems:</para>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>An invalid bus object was passed.</para></listitem>
</varlistentry>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ECHILD</constant></term>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<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>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ENOTCONN</constant></term>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The bus connection has been terminated already.</para></listitem>
</varlistentry>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ECONNRESET</constant></term>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The bus connection has been terminated just now.</para></listitem>
</varlistentry>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EBUSY</constant></term>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>This function is already being called, i.e. <function>sd_bus_process()</function>
has been called from a callback function that itself was called by
<function>sd_bus_process()</function>.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
man: substantially update the docs regarding hooking sd-bus objects up with external event loops Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html This also drops all references to select() from our manpages. It's 2018 after all, people should use poll(), or ppoll() or epoll().
2018-12-12 19:31:05 +08:00
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
man: add version information for functions
2023-09-04 20:46:35 +08:00
<refsect1>
<title>History</title>
man: fix wrong version info (#31949) Fixes #31920.
2024-04-18 08:45:51 +08:00
<para><function>sd_bus_process()</function> was added in version 221.</para>
man: add version information for functions
2023-09-04 20:46:35 +08:00
</refsect1>
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
man: document some sd-bus functions (#3567) * sd_bus_add_match * sd_bus_get_fd * sd_bus_message_read_basic * sd_bus_process
2016-06-21 23:52:32 +08:00
</refsect1>
</refentry>
Reference in New Issue Copy Permalink