1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/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> 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 > 0) an incoming message will not be considered handled,
and be passed to other suitable handlers (until one returns > > 0), or returned by
<function>sd_bus_process()</function> (in case none returns > 0).</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 221.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<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>
</refsect1>
</refentry>
|
