2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright © 2016 Julian Orth
11 <refentry id=
"sd_bus_wait" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
14 <title>sd_bus_wait
</title>
15 <productname>systemd
</productname>
19 <refentrytitle>sd_bus_wait
</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_wait
</refname>
26 <refpurpose>Wait for I/O on a bus connection
</refpurpose>
31 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
34 <funcdef>int
<function>sd_bus_wait
</function></funcdef>
35 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
36 <paramdef>uint64_t
<parameter>timeout_usec
</parameter></paramdef>
42 <title>Description
</title>
44 <para><function>sd_bus_wait()
</function> synchronously waits for I/O on the specified bus connection object. This
45 function is supposed to be called whenever
46 <citerefentry><refentrytitle>sd_bus_process
</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns zero,
47 indicating that no work is pending on the connection. Internally, this call invokes
<citerefentry
48 project='man-pages'
><refentrytitle>ppoll
</refentrytitle><manvolnum>3</manvolnum></citerefentry>, to wait for I/O on
49 the bus connection. If the
<parameter>timeout_sec
</parameter> parameter is specified, the call will block at most
50 for the specified amount of time in µs. Pass
<constant>UINT64_MAX
</constant> to permit it to sleep
53 <para>After each invocation of
<function>sd_bus_wait()
</function> the
<function>sd_bus_process()
</function> call
54 should be invoked in order to process any now pending I/O work.
</para>
56 <para>Note that
<function>sd_bus_wait()
</function> is suitable only for simple programs as it does not permit
57 waiting for other I/O events. For more complex programs either connect the bus connection object to an external
58 event loop using
<citerefentry><refentrytitle>sd_bus_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
59 or to an
<citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop
61 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
65 <title>Return Value
</title>
67 <para>If any I/O was seen, a positive value is returned, zero otherwise. If an error occurs, a negative
68 <varname>errno
</varname>-style error code is returned.
</para>
73 <para>Returned errors may indicate the following problems:
</para>
77 <term><constant>-EINVAL
</constant></term>
79 <listitem><para>An invalid bus object was passed.
</para></listitem>
83 <term><constant>-ECHILD
</constant></term>
85 <listitem><para>The bus connection was allocated in a parent process and is being reused in a child
86 process after
<function>fork()
</function>.
</para></listitem>
90 <term><constant>-ENOTCONN
</constant></term>
92 <listitem><para>The bus connection has been terminated already.
</para></listitem>
98 <xi:include href=
"libsystemd-pkgconfig.xml" />
101 <title>See Also
</title>
104 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
105 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
106 <citerefentry><refentrytitle>sd_bus_process
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>sd_bus_get_fd
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
108 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>sd_bus_attach_event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>