2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2016 Julian Orth
11 <refentry id=
"sd_bus_process" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
14 <title>sd_bus_process
</title>
15 <productname>systemd
</productname>
19 <refentrytitle>sd_bus_process
</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_process
</refname>
26 <refpurpose>Drive the connection
</refpurpose>
31 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
34 <funcdef>int
<function>sd_bus_process
</function></funcdef>
35 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
36 <paramdef>sd_bus_message **
<parameter>ret
</parameter></paramdef>
42 <title>Description
</title>
44 <para><function>sd_bus_process()
</function> drives the connection between the client and the message bus. That is,
45 it handles connecting, authentication, and message processing. When invoked pending I/O work is executed, and
46 queued incoming messages are dispatched to registered callbacks. Each time it is invoked a single operation is
47 executed. It returns zero when no operations were pending and positive if a message was processed. When zero is
48 returned the caller should synchronously poll for I/O events before calling into
49 <function>sd_bus_process()
</function> again. For that either user the simple, synchronous
50 <citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry> call, or hook up
51 the bus connection object to an external or manual event loop using
52 <citerefentry><refentrytitle>sd_bus_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
55 <para><function>sd_bus_process()
</function> processes at most one incoming message per call. If the parameter
56 <parameter>ret
</parameter> is not
<constant>NULL
</constant> and the call processed a message,
57 <parameter>*ret
</parameter> is set to this message. The caller owns a reference to this message and should call
58 <citerefentry><refentrytitle>sd_bus_message_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry> when the
59 message is no longer needed. If
<parameter>ret
</parameter> is not NULL, progress was made, but no message was
60 processed,
<parameter>*ret
</parameter> is set to
<constant>NULL
</constant>.
</para>
62 <para>If a the bus object is connected to an
63 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop (with
64 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it is not
65 necessary to call
<function>sd_bus_process()
</function> directly as it is invoked automatically when
70 <title>Return Value
</title>
72 <para>If progress was made, a positive integer is returned. If no progress was made,
0 is returned. If an error
73 occurs, a negative
<varname>errno
</varname>-style error code is returned.
</para>
79 <para>Returned errors may indicate the following problems:
</para>
83 <term><constant>-EINVAL
</constant></term>
85 <listitem><para>An invalid bus object was passed.
</para></listitem>
89 <term><constant>-ECHILD
</constant></term>
91 <listitem><para>The bus connection was allocated in a parent process and is being reused in a child process
92 after
<function>fork()
</function>.
</para></listitem>
96 <term><constant>-ENOTCONN
</constant></term>
98 <listitem><para>The bus connection has been terminated already.
</para></listitem>
102 <term><constant>-ECONNRESET
</constant></term>
104 <listitem><para>The bus connection has been terminated just now.
</para></listitem>
108 <term><constant>-EBUSY
</constant></term>
110 <listitem><para>This function is already being called, i.e.
<function>sd_bus_process()
</function> has been
111 called from a callback function that itself was called by
112 <function>sd_bus_process()
</function>.
</para></listitem>
117 <xi:include href=
"libsystemd-pkgconfig.xml" />
120 <title>See Also
</title>
123 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
124 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
125 <citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
126 <citerefentry><refentrytitle>sd_bus_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
127 <citerefentry><refentrytitle>sd_bus_message_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
128 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
129 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>