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<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_run</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_run</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_run</refname> 20 <refname>sd_event_loop</refname> 21 22 <refpurpose>Run an event loop</refpurpose> 23 </refnamediv> 24 25 <refsynopsisdiv> 26 <funcsynopsis> 27 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 28 29 <funcprototype> 30 <funcdef>int <function>sd_event_run</function></funcdef> 31 <paramdef>sd_event *<parameter>event</parameter></paramdef> 32 <paramdef>uint64_t <parameter>usec</parameter></paramdef> 33 </funcprototype> 34 35 <funcprototype> 36 <funcdef>int <function>sd_event_loop</function></funcdef> 37 <paramdef>sd_event *<parameter>event</parameter></paramdef> 38 </funcprototype> 39 </funcsynopsis> 40 </refsynopsisdiv> 41 42 <refsect1> 43 <title>Description</title> 44 45 <para><function>sd_event_run()</function> may be used to run a single 46 iteration of the event loop specified in the 47 <parameter>event</parameter> parameter. The function waits until an event to 48 process is available, and dispatches the registered handler for 49 it. The <parameter>usec</parameter> parameter specifies the 50 maximum time (in microseconds) to wait for an event. Use 51 <constant>(uint64_t) -1</constant> to specify an infinite 52 timeout.</para> 53 54 <para><function>sd_event_loop()</function> invokes 55 <function>sd_event_run()</function> in a loop, thus implementing 56 the actual event loop. The call returns as soon as exiting was 57 requested using 58 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 59 60 <para>The event loop object <parameter>event</parameter> is 61 created with 62 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 63 Events sources to wait for and their handlers may be registered 64 with 65 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 66 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 67 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 68 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 69 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 70 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> 71 and 72 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 73 </para> 74 75 <para>For low-level control of event loop execution, use 76 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 77 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> 78 and 79 <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry> 80 which are wrapped by <function>sd_event_run()</function>. Along 81 with 82 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 83 these functions allow integration of an 84 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> 85 event loop into foreign event loop implementations.</para> 86 </refsect1> 87 88 <refsect1> 89 <title>Return Value</title> 90 91 <para>On failure, these functions return a negative errno-style 92 error code. <function>sd_event_run()</function> returns a 93 positive, non-zero integer if an event source was dispatched, and 94 zero when the specified timeout hit before an event source has 95 seen any event, and hence no event source was 96 dispatched. <function>sd_event_loop()</function> returns the exit 97 code specified when invoking 98 <function>sd_event_exit()</function>.</para> 99 100 <refsect2> 101 <title>Errors</title> 102 103 <para>Returned errors may indicate the following problems:</para> 104 105 <variablelist> 106 <varlistentry> 107 <term><constant>-EINVAL</constant></term> 108 109 <listitem><para>The <parameter>event</parameter> parameter is invalid or 110 <constant>NULL</constant>.</para></listitem> 111 </varlistentry> 112 113 <varlistentry> 114 <term><constant>-EBUSY</constant></term> 115 116 <listitem><para>The event loop object is not in the right 117 state (see 118 <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> 119 for an explanation of possible states).</para></listitem> 120 </varlistentry> 121 122 <varlistentry> 123 <term><constant>-ESTALE</constant></term> 124 125 <listitem><para>The event loop is already terminated.</para></listitem> 126 127 </varlistentry> 128 129 <varlistentry> 130 <term><constant>-ECHILD</constant></term> 131 132 <listitem><para>The event loop has been created in a different process.</para></listitem> 133 134 </varlistentry> 135 136 </variablelist> 137 138 <para>Other errors are possible, too.</para> 139 </refsect2> 140 </refsect1> 141 142 <xi:include href="libsystemd-pkgconfig.xml" /> 143 144 <refsect1> 145 <title>See Also</title> 146 147 <para> 148 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 149 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 150 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 151 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 152 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 153 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 154 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 155 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 156 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 157 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 158 <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 159 <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 160 <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink> 161 </para> 162 </refsect1> 163 164</refentry> 165