sd_event_wait.xml revision b938cb902c3b5bca807a94b277672c64d6767886
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen This file is part of systemd.
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen Copyright 2015 Zbigniew Jędrzejewski-Szmek
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen systemd is free software; you can redistribute it and/or modify it
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen under the terms of the GNU Lesser General Public License as published by
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen the Free Software Foundation; either version 2.1 of the License, or
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen (at your option) any later version.
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen systemd is distributed in the hope that it will be useful, but
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen WITHOUT ANY WARRANTY; without even the implied warranty of
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen Lesser General Public License for more details.
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen You should have received a copy of the GNU Lesser General Public License
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen along with systemd; If not, see <http://www.gnu.org/licenses/>.
07630cea1f3a845c09309f197ac7c4f11edd3b62Lennart Poettering </authorgroup>
07630cea1f3a845c09309f197ac7c4f11edd3b62Lennart Poettering </refentryinfo>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <refentrytitle>sd_event_wait</refentrytitle>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <refname>sd_event_wait</refname>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <refname>sd_event_prepare</refname>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <refname>sd_event_dispatch</refname>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <refpurpose>Run parts of libsystemd event loop</refpurpose>
d5d8429a12c4b1ef0dcd226c0904f00f4fa4898aLennart Poettering <refsynopsisdiv>
d5d8429a12c4b1ef0dcd226c0904f00f4fa4898aLennart Poettering <funcsynopsis>
d5d8429a12c4b1ef0dcd226c0904f00f4fa4898aLennart Poettering <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
d5d8429a12c4b1ef0dcd226c0904f00f4fa4898aLennart Poettering <funcprototype>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <funcdef>int <function>sd_event_prepare</function></funcdef>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <paramdef>sd_event *<parameter>event</parameter></paramdef>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <funcdef>int <function>sd_event_wait</function></funcdef>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <paramdef>sd_event *<parameter>event</parameter></paramdef>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <paramdef>uint64_t <parameter>timeout</parameter></paramdef>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <funcdef>int <function>sd_event_dispatch</function></funcdef>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek </funcprototype>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen </refsynopsisdiv>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <para>Functions described here form parts of an event loop.</para>
260ad50f5b4a9795032e3119c64f838a2d03370dThomas Hindoe Paaboel Andersen <para><function>sd_event_prepare</function> checks for pending
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen events and arms necessary timers. If any events are ready to be
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen processed, it returns a positive value, and the events should be
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen processed with <function>sd_event_dispatch</function>.
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <function>sd_event_dispatch</function> runs a handler for one of
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen the events from the sources with the highest priority. On success,
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <function>sd_event_dispatch</function> returns either 0, which
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek means that the loop is finished, or a positive value, which means
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek that the loop is again in the initial state and
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <function>sd_event_prepare</function> should be called again.
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <para>In case <function>sd_event_prepare</function> returned 0,
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <function>sd_event_wait</function> should be called to wait for
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek events or a timeout. If any events are ready to be processed, it
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek returns a positive value, and the events should be processed with
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <function>sd_event_dispatch</function>. Otherwise, the loop is
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek back in the initial state and <function>sd_event_prepare</function>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek should be called again.</para>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <programlisting>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek │ initial ├──←←←←←←←←←←←←←←←←←←←─┐
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek sd_event_prepare ┌─────────┐ ↑
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek ├ 0 →→→→→→→──┤ armed │ ↑
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen ↓ sd_event_wait ↑
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen ├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen sd_event_dispatch ↑
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen ├ 1 ──────────→→→→→→→─────────┘
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen </programlisting>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <para>All three functions as the first argument take the event
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen loop object <parameter>event</parameter> that is created with with
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <function>sd_event_new</function>. The timeout for
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <function>sd_event_wait</function> is specified with
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <parameter>timeout</parameter> in milliseconds.
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <constant>(uint64_t) -1</constant> may be used to specify an
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen infinite timeout.</para>
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <para>On success, these functions return 0 or a positive integer.
b7e7184634d573fb73143210962acce205f37f61Michael Biebl On failure, they return a negative errno-style error code. In case
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <function>sd_event_wait</function>, a positive value means that
b7e7184634d573fb73143210962acce205f37f61Michael Biebl events are ready to be processed and 0 means that no events are
b7e7184634d573fb73143210962acce205f37f61Michael Biebl ready. In case of <function>sd_event_dispatch</function>, a
b7e7184634d573fb73143210962acce205f37f61Michael Biebl positive value means that the loop is again in the initial state
b7e7184634d573fb73143210962acce205f37f61Michael Biebl and 0 means the loop is finished. For any of these functions, a
b7e7184634d573fb73143210962acce205f37f61Michael Biebl negative return value means the loop must be aborted.</para>
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <para>Returned errors may indicate the following problems:</para>
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <variablelist>
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <varlistentry>
b7e7184634d573fb73143210962acce205f37f61Michael Biebl <listitem><para>Parameter <parameter>event</parameter> is
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <constant>NULL</constant>.</para></listitem>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <term><constant>-EBUSY</constant></term>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <listitem><para>The event loop object is not in the right
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <term><constant>-ESTALE</constant></term>
8fba1c8d4e3d05d2af2848b6570bdc09e725d06eZbigniew Jędrzejewski-Szmek <listitem><para>The event loop is already terminated.</para></listitem>
77354c7e6f096a447245a8781c1eaa4acbe67089Martin Pitt <varlistentry>
77354c7e6f096a447245a8781c1eaa4acbe67089Martin Pitt <listitem><para>The event loop has been created in a different process.</para></listitem>
77354c7e6f096a447245a8781c1eaa4acbe67089Martin Pitt </varlistentry>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <para>Functions described here are available
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen as a shared library, which can be compiled and linked to with the
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95ed3294c632f5606327149f10cef1eb34422862Thomas Hindoe Paaboel Andersen <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>.