chiark / gitweb /
check for _POSIX_C_SOURCE instead of __USE_POSIX*
[elogind.git] / man / sd_bus_process.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2016 Julian Orth
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_bus_process">
25
26   <refentryinfo>
27     <title>sd_bus_process</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
32         <firstname>Julian</firstname>
33         <surname>Orth</surname>
34         <email>ju.orth@gmail.com</email>
35       </author>
36     </authorgroup>
37   </refentryinfo>
38
39   <refmeta>
40     <refentrytitle>sd_bus_process</refentrytitle>
41     <manvolnum>3</manvolnum>
42   </refmeta>
43
44   <refnamediv>
45     <refname>sd_bus_process</refname>
46
47     <refpurpose>Drive the connection</refpurpose>
48   </refnamediv>
49
50   <refsynopsisdiv>
51     <funcsynopsis>
52       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
53
54       <funcprototype>
55         <funcdef>int <function>sd_bus_process</function></funcdef>
56         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
57         <paramdef>sd_bus_message **<parameter>r</parameter></paramdef>
58       </funcprototype>
59     </funcsynopsis>
60   </refsynopsisdiv>
61
62   <refsect1>
63     <title>Description</title>
64
65     <para>
66       <function>sd_bus_process()</function> drives the connection between the
67       message bus and the client. That is, it handles connecting,
68       authentication, and message processing. It should be called in a loop
69       until no further progress can be made or an error occurs.
70     </para>
71
72     <para>
73       Once no further progress can be made,
74       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
75       should be called. Alternatively the user can wait for incoming data on
76       the file descriptor returned by
77       <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
78     </para>
79
80     <para>
81       <function>sd_bus_process</function> processes at most one incoming
82       message per call.  If the parameter <parameter>r</parameter> is not NULL
83       and the call processed a message, <code>*r</code> is set to this message.
84       The caller owns a reference to this message and should call
85       <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
86       when the message is no longer needed. If <parameter>r</parameter> is not
87       NULL, progress was made, but no message was processed, <code>*r</code> is
88       set to NULL.
89     </para>
90   </refsect1>
91
92   <refsect1>
93     <title>Return Value</title>
94
95     <para>
96       If progress was made, a positive integer is returned. If no progress was
97       made, 0 is returned. If an error occurs, a negative errno-style error code
98       is returned.
99     </para>
100   </refsect1>
101
102   <refsect1>
103     <title>See Also</title>
104
105     <para>
106       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
107       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
108     </para>
109   </refsect1>
110
111 </refentry>