mirror of
https://github.com/systemd/systemd.git
synced 2024-12-25 01:34:28 +03:00
83d0edf565
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".
139 lines
5.6 KiB
XML
139 lines
5.6 KiB
XML
<?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_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 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
|
|
<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 <constant>NULL</constant>, progress was made, but no message was
|
|
processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</para>
|
|
|
|
<para>If 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>
|
|
|
|
<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>-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>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>History</title>
|
|
<para><function>sd_bus_process()</function> was added in version 231.</para>
|
|
</refsect1>
|
|
|
|
<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>
|