sd_event_run.xml revision dc83f27a7cf03757dec11a69ec18504ad4ea8f89
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek This file is part of systemd.
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek Copyright 2015 Zbigniew Jędrzejewski-Szmek
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek (at your option) any later version.
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude">
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <productname>systemd</productname>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <refentrytitle>sd_event_run</refentrytitle>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <refname>sd_event_loop</refname>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <refpurpose>Run an event loop</refpurpose>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <refsynopsisdiv>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_event_run</function></funcdef>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>uint64_t <parameter>usec</parameter></paramdef>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek </funcprototype>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_event_loop</function></funcdef>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek </funcprototype>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><function>sd_event_run()</function> may be used to run a single
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering iteration of the event loop specified in the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <parameter>event</parameter> parameter. The function waits until an event to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering process is available, and dispatches the registered handler for
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering it. The <parameter>usec</parameter> parameter specifies the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering maximum time (in microseconds) to wait for an event. Use
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>(uint64_t) -1</constant> to specify an infinite
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering timeout.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para><function>sd_event_loop()</function> invokes
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_run()</function> in a loop, thus implementing
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering the actual event loop. The call returns as soon as exiting was
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering requested using
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <para>The event loop object <parameter>event</parameter> is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering Events sources to wait for and their handlers may be registered
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>For low-level control of event loop execution, use
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering which are wrapped by <function>sd_event_run()</function>. Along
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering these functions allow integration of an
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event loop into foreign event loop implementations.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>On failure, these functions return a negative errno-style
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering error code. <function>sd_event_run()</function> returns a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering positive, non-zero integer if an event source was dispatched, and
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering zero when the specified timeout hit before an event source has
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering seen any event, and hence no event source was
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering dispatched. <function>sd_event_loop()</function> returns the exit
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering code specified when invoking
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <function>sd_event_exit()</function>.</para>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <listitem><para>The <parameter>event</parameter> parameter is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering invalid or <constant>NULL</constant>.</para></listitem>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <term><constant>-EBUSY</constant></term>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <listitem><para>The event loop object is not in the right
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek for an explanation of possible states).</para></listitem>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <term><constant>-ESTALE</constant></term>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <listitem><para>The event loop is already terminated.</para></listitem>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <term><constant>-ECHILD</constant></term>
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <listitem><para>The event loop has been created in a different process.</para></listitem>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <xi:include href="libsystemd-pkgconfig.xml" />
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
42f1ab5009eed71f0d4f83681b8fdbed8664fca3Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
c268628a20e684d6079de6e5da96c10429e6ed1eZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>.