1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_event_add_defer" conditional="ENABLE_KDBUS">
27 <title>sd_event_add_defer</title>
28 <productname>systemd</productname>
32 <contrib>More text</contrib>
33 <firstname>Zbigniew</firstname>
34 <surname>Jędrzejewski-Szmek</surname>
35 <email>zbyszek@in.waw.pl</email>
41 <refentrytitle>sd_event_add_defer</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_event_add_defer</refname>
47 <refname>sd_event_add_post</refname>
48 <refname>sd_event_add_exit</refname>
50 <refpurpose>Add static event sources to an event loop</refpurpose>
55 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
58 <funcdef>int <function>sd_event_add_defer</function></funcdef>
59 <paramdef>sd_event *<parameter>event</parameter></paramdef>
60 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
61 <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
62 <paramdef>void *<parameter>userdata</parameter></paramdef>
66 <funcdef>int <function>sd_event_add_post</function></funcdef>
67 <paramdef>sd_event *<parameter>event</parameter></paramdef>
68 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
69 <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
70 <paramdef>void *<parameter>userdata</parameter></paramdef>
74 <funcdef>int <function>sd_event_add_exit</function></funcdef>
75 <paramdef>sd_event *<parameter>event</parameter></paramdef>
76 <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
77 <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
78 <paramdef>void *<parameter>userdata</parameter></paramdef>
82 <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
83 <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
84 <paramdef>void *<parameter>userdata</parameter></paramdef>
91 <title>Description</title>
93 <para>Those three functions add new event sources to an event loop
94 object. The event loop is specified in
95 <parameter>event</parameter>, the event source is returned in the
96 <parameter>source</parameter> parameter. The event sources are
97 enabled statically and will "fire" when the event loop is run and
98 the conditions described below are met. The handler function will
99 be passed the <parameter>userdata</parameter> pointer, which may
100 be chosen freely by the caller.</para>
102 <para><function>sd_event_add_defer()</function> adds a new event
103 source that will "fire" the next time the event loop is run. By
104 default, the handler will be called once
105 (<constant>SD_EVENT_ONESHOT</constant>).</para>
107 <para><function>sd_event_add_post()</function> adds a new event
108 source that will "fire" if any event handlers are invoked whenever
109 the event loop is run. By default, the source is enabled
110 permanently (<constant>SD_EVENT_ON</constant>).</para>
112 <para><function>sd_event_add_exit()</function> adds a new event
113 source that will "fire" when the event loop is terminated
114 with <function>sd_event_exit()</function>.</para>
117 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
118 function may be used to enable the event source permanently
119 (<constant>SD_EVENT_ON</constant>) or to make it fire just once
120 (<constant>SD_EVENT_ONESHOT</constant>). If the handler function
121 returns a negative error code, it will be disabled after the
122 invocation, even if <constant>SD_EVENT_ON</constant> mode is
127 <title>Return Value</title>
129 <para>On success, this functions return 0 or a positive
130 integer. On failure, they return a negative errno-style error
135 <title>Errors</title>
137 <para>Returned errors may indicate the following problems:</para>
141 <term><constant>-ENOMEM</constant></term>
143 <listitem><para>Not enough memory to allocate an object.</para></listitem>
147 <term><constant>-EINVAL</constant></term>
149 <listitem><para>An invalid argument has been passed.</para></listitem>
153 <term><constant>-ESTALE</constant></term>
155 <listitem><para>The event loop is already terminated.</para></listitem>
159 <term><constant>-ECHILD</constant></term>
161 <listitem><para>The event loop has been created in a different process.</para></listitem>
170 <para>Functions described here are available as a shared library,
171 which can be compiled and linked to with the
172 <constant>libsystemd</constant> <citerefentry
173 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
178 <title>See Also</title>
181 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
186 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
187 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>