sd_event_add_defer.xml revision 7f3fdb7f19a109fa3d1be92926bfe4cea1817da5
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew 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">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Zbigniew Jędrzejewski-Szmek
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering<refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude">
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <title>sd_event_add_defer</title>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <productname>systemd</productname>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <surname>Jędrzejewski-Szmek</surname>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <email>zbyszek@in.waw.pl</email>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refentrytitle>sd_event_add_defer</refentrytitle>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refname>sd_event_add_defer</refname>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refname>sd_event_add_post</refname>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refname>sd_event_add_exit</refname>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refpurpose>Add static event sources to an event loop</refpurpose>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcprototype>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <paramdef>void *<parameter>userdata</parameter></paramdef>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering </funcprototype>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_event_add_defer</function></funcdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>void *<parameter>userdata</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek </funcprototype>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_event_add_post</function></funcdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>void *<parameter>userdata</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek </funcprototype>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_event_add_exit</function></funcdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event *<parameter>event</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <paramdef>void *<parameter>userdata</parameter></paramdef>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek </funcprototype>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>These three functions add new static event sources to an
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event loop. The event loop object is specified in the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <parameter>event</parameter> parameter, the event source object is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering returned in the <parameter>source</parameter> parameter. The event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering sources are enabled statically and will "fire" when the event loop
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering is run and the conditions described below are met. The handler
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering function will be passed the <parameter>userdata</parameter>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering pointer, which may be chosen freely by the caller.</para>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <para><function>sd_event_add_defer()</function> adds a new event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source that will be dispatched instantly, before the event loop
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering goes to sleep again and waits for new events. By default, the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering handler will be called once
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source is set to <constant>SD_EVENT_ON</constant> the event loop
7f3fdb7f19a109fa3d1be92926bfe4cea1817da5Jakub Wilk will never go to sleep again, but continuously call the handler,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering possibly interleaved with other event sources.</para>
f49481d0ca170ea567b46fde6c1c089b1dbb49cbTom Gundersen <para><function>sd_event_add_post()</function> adds a new event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source that is run before the event loop will sleep and wait
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering for new events, but only after at least one other non-post event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source was dispatched. By default, the source is enabled
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering permanently (<constant>SD_EVENT_ON</constant>). Note that this
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering event source type will still allow the event loop to go to sleep
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering again, even if set to <constant>SD_EVENT_ON</constant>, as long as
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering no other event source is ever triggered.</para>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <para><function>sd_event_add_exit()</function> adds a new event
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering source that will be dispatched when the event loop is terminated
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek function may be used to enable the event source permanently
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek (<constant>SD_EVENT_ON</constant>) or to make it fire just once
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering (<constant>SD_EVENT_ONESHOT</constant>).</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>If the handler function returns a negative error code, it
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering will be disabled after the invocation, even if the
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <constant>SD_EVENT_ON</constant> mode was requested before.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>To destroy an event source object use
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering but note that the event source is only removed from the event loop
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering when all references to the event source are dropped. To make sure
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering an event source does not fire anymore, even when there's still a
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering reference to it kept, consider setting the event source to
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <para>If the second parameter of these functions is passed as
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering NULL no reference to the event source object is returned. In this
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering case the event source is considered "floating", and will be
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering destroyed implicitly when the event loop itself is
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering destroyed.</para>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <para>On success, this functions return 0 or a positive
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek integer. On failure, they return a negative errno-style error
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <listitem><para>Not enough memory to allocate an object.</para></listitem>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <listitem><para>An invalid argument has been passed.</para></listitem>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ESTALE</constant></term>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <listitem><para>The event loop is already terminated.</para></listitem>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ECHILD</constant></term>
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew 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" />
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4dfefc1914bad6a025e2d6738999e45b74715002Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
dc83f27a7cf03757dec11a69ec18504ad4ea8f89Lennart Poettering <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>