summaryrefslogtreecommitdiff
path: root/man/sd_bus_process.xml
blob: 193c16c6a5d456d25ae495d534e139f5a267a0a7 (plain)
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
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/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 &lt;systemd/sd-bus.h&gt;</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 message processing. 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 synchronously poll for I/O events before calling into
    <function>sd_bus_process()</function> again. For that either use the simple, synchronous
    <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>, progress was made, but no message was
    processed, <parameter>*ret</parameter> is set to <constant>NULL</constant>.</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>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>