2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1-or-later
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.
45 That is, it handles connecting, authentication, and processing of messages. When invoked, pending I/O
46 work is executed, and queued incoming messages are dispatched to registered callbacks. Each time it is
47 invoked a single operation is executed. It returns zero when no operations were pending and positive if a
48 message was processed. When zero is returned the caller should poll for I/O events before calling into
49 <function>sd_bus_process()
</function> again. For that either use the simple, blocking
50 <citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry> call, or
51 hook up 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
<constant>NULL
</constant>, progress was made, but no message was
60 processed,
<parameter>*ret
</parameter> is set to
<constant>NULL
</constant>.
</para>
62 <para>If 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
73 error occurs, a negative
<varname>errno
</varname>-style error code is returned.
</para>
78 <para>Returned errors may indicate the following problems:
</para>
82 <term><constant>-EINVAL
</constant></term>
84 <listitem><para>An invalid bus object was passed.
</para></listitem>
88 <term><constant>-ECHILD
</constant></term>
90 <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
91 process after
<function>fork()
</function>.
</para></listitem>
95 <term><constant>-ENOTCONN
</constant></term>
97 <listitem><para>The bus connection has been terminated already.
</para></listitem>
101 <term><constant>-ECONNRESET
</constant></term>
103 <listitem><para>The bus connection has been terminated just now.
</para></listitem>
107 <term><constant>-EBUSY
</constant></term>
109 <listitem><para>This function is already being called, i.e.
<function>sd_bus_process()
</function>
110 has been called from a callback function that itself was called by
111 <function>sd_bus_process()
</function>.
</para></listitem>
117 <xi:include href=
"libsystemd-pkgconfig.xml" />
120 <title>History
</title>
121 <para><function>sd_bus_process()
</function> was added in version
221.
</para>
125 <title>See Also
</title>
127 <para><simplelist type=
"inline">
128 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
129 <member><citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
130 <member><citerefentry><refentrytitle>sd_bus_wait
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
131 <member><citerefentry><refentrytitle>sd_bus_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
132 <member><citerefentry><refentrytitle>sd_bus_message_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
133 <member><citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
134 <member><citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>