man/sd_bus_wait.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1-or-later
   7
   8   Copyright © 2016 Julian Orth
   9 -->
  10
  11 <refentry id="sd_bus_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_bus_wait</title>
  15     <productname>systemd</productname>
  16   </refentryinfo>
  17
  18   <refmeta>
  19     <refentrytitle>sd_bus_wait</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>sd_bus_wait</refname>
  25
  26     <refpurpose>Wait for I/O on a bus connection</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  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>
  37       </funcprototype>
  38     </funcsynopsis>
  39   </refsynopsisdiv>
  40
  41   <refsect1>
  42     <title>Description</title>
  43
  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>2</manvolnum></citerefentry>, to wait for I/O on
  49     the bus connection. If the <parameter>timeout_usec</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
  51     indefinitely.</para>
  52
  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>
  55
  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
  60     using
  61     <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  62   </refsect1>
  63
  64   <refsect1>
  65     <title>Return Value</title>
  66
  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>
  69
  70     <refsect2>
  71       <title>Errors</title>
  72
  73       <para>Returned errors may indicate the following problems:</para>
  74
  75       <variablelist>
  76         <varlistentry>
  77           <term><constant>-EINVAL</constant></term>
  78
  79           <listitem><para>An invalid bus object was passed.</para></listitem>
  80         </varlistentry>
  81
  82         <varlistentry>
  83           <term><constant>-ECHILD</constant></term>
  84
  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>
  87         </varlistentry>
  88
  89         <varlistentry>
  90           <term><constant>-ENOTCONN</constant></term>
  91
  92           <listitem><para>The bus connection has been terminated already.</para></listitem>
  93         </varlistentry>
  94       </variablelist>
  95     </refsect2>
  96   </refsect1>
  97
  98   <xi:include href="libsystemd-pkgconfig.xml" />
  99
 100   <refsect1>
 101     <title>History</title>
 102     <para><function>sd_bus_wait()</function> was added in version 240.</para>
 103   </refsect1>
 104
 105   <refsect1>
 106     <title>See Also</title>
 107
 108     <para>
 109       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 110       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 111       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 112       <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 113       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 114       <citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 115     </para>
 116   </refsect1>
 117
 118 </refentry>