]>
Commit | Line | Data |
---|---|---|
6e866b33 | 1 | <?xml version='1.0'?> |
bb4f798a MB |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
5a920b42 MP |
4 | |
5 | <!-- | |
52ad194e MB |
6 | SPDX-License-Identifier: LGPL-2.1+ |
7 | ||
b012e921 | 8 | Copyright © 2016 Julian Orth |
5a920b42 MP |
9 | --> |
10 | ||
6e866b33 | 11 | <refentry id="sd_bus_process" xmlns:xi="http://www.w3.org/2001/XInclude"> |
5a920b42 MP |
12 | |
13 | <refentryinfo> | |
14 | <title>sd_bus_process</title> | |
15 | <productname>systemd</productname> | |
5a920b42 MP |
16 | </refentryinfo> |
17 | ||
18 | <refmeta> | |
19 | <refentrytitle>sd_bus_process</refentrytitle> | |
20 | <manvolnum>3</manvolnum> | |
21 | </refmeta> | |
22 | ||
23 | <refnamediv> | |
24 | <refname>sd_bus_process</refname> | |
25 | ||
26 | <refpurpose>Drive the connection</refpurpose> | |
27 | </refnamediv> | |
28 | ||
29 | <refsynopsisdiv> | |
30 | <funcsynopsis> | |
31 | <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> | |
32 | ||
33 | <funcprototype> | |
34 | <funcdef>int <function>sd_bus_process</function></funcdef> | |
35 | <paramdef>sd_bus *<parameter>bus</parameter></paramdef> | |
6e866b33 | 36 | <paramdef>sd_bus_message **<parameter>ret</parameter></paramdef> |
5a920b42 MP |
37 | </funcprototype> |
38 | </funcsynopsis> | |
39 | </refsynopsisdiv> | |
40 | ||
41 | <refsect1> | |
42 | <title>Description</title> | |
43 | ||
6e866b33 MB |
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>. | |
5a920b42 MP |
53 | </para> |
54 | ||
6e866b33 MB |
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> | |
61 | ||
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 | |
66 | necessary.</para> | |
5a920b42 MP |
67 | </refsect1> |
68 | ||
69 | <refsect1> | |
70 | <title>Return Value</title> | |
71 | ||
bb4f798a MB |
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> | |
5a920b42 | 74 | |
bb4f798a MB |
75 | <refsect2> |
76 | <title>Errors</title> | |
6e866b33 | 77 | |
bb4f798a | 78 | <para>Returned errors may indicate the following problems:</para> |
6e866b33 | 79 | |
bb4f798a MB |
80 | <variablelist> |
81 | <varlistentry> | |
82 | <term><constant>-EINVAL</constant></term> | |
6e866b33 | 83 | |
bb4f798a MB |
84 | <listitem><para>An invalid bus object was passed.</para></listitem> |
85 | </varlistentry> | |
6e866b33 | 86 | |
bb4f798a MB |
87 | <varlistentry> |
88 | <term><constant>-ECHILD</constant></term> | |
6e866b33 | 89 | |
bb4f798a MB |
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> | |
92 | </varlistentry> | |
6e866b33 | 93 | |
bb4f798a MB |
94 | <varlistentry> |
95 | <term><constant>-ENOTCONN</constant></term> | |
6e866b33 | 96 | |
bb4f798a MB |
97 | <listitem><para>The bus connection has been terminated already.</para></listitem> |
98 | </varlistentry> | |
6e866b33 | 99 | |
bb4f798a MB |
100 | <varlistentry> |
101 | <term><constant>-ECONNRESET</constant></term> | |
6e866b33 | 102 | |
bb4f798a MB |
103 | <listitem><para>The bus connection has been terminated just now.</para></listitem> |
104 | </varlistentry> | |
6e866b33 | 105 | |
bb4f798a MB |
106 | <varlistentry> |
107 | <term><constant>-EBUSY</constant></term> | |
6e866b33 | 108 | |
bb4f798a MB |
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> | |
112 | </varlistentry> | |
113 | </variablelist> | |
114 | </refsect2> | |
6e866b33 MB |
115 | </refsect1> |
116 | ||
117 | <xi:include href="libsystemd-pkgconfig.xml" /> | |
118 | ||
5a920b42 MP |
119 | <refsect1> |
120 | <title>See Also</title> | |
121 | ||
122 | <para> | |
123 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
124 | <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
6e866b33 MB |
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> | |
5a920b42 MP |
130 | </para> |
131 | </refsect1> | |
132 | ||
133 | </refentry> |