mirror of
https://github.com/systemd/systemd.git
synced 2024-12-01 06:13:38 +08:00
ffd1a3f688
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().
134 lines
5.4 KiB
XML
134 lines
5.4 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
SPDX-License-Identifier: LGPL-2.1+
|
|
|
|
Copyright © 2016 Julian Orth
|
|
-->
|
|
|
|
<refentry id="sd_bus_process" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<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 <systemd/sd-bus.h></funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_bus_process</function></funcdef>
|
|
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
|
<paramdef>sd_bus_message **<parameter>ret</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><function>sd_bus_process()</function> drives the connection between the client and the message bus. That is,
|
|
it handles connecting, authentication, and message processing. 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 synchronously poll for I/O events before calling into
|
|
<function>sd_bus_process()</function> again. For that either user the simple, synchronous
|
|
<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
|
|
<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
|
</para>
|
|
|
|
<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 NULL, progress was made, but no message was
|
|
processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</para>
|
|
|
|
<para>If a the bus object is connected to an
|
|
<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>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<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>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<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>-ENOTCONN</constant></term>
|
|
|
|
<listitem><para>The bus connection has been terminated already.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-ECONNRESET</constant></term>
|
|
|
|
<listitem><para>The bus connection has been terminated just now.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-EBUSY</constant></term>
|
|
|
|
<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>
|
|
</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_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|