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 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_event_add_defer" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_event_add_defer
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_event_add_defer
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_event_add_defer
</refname>
23 <refname>sd_event_add_post
</refname>
24 <refname>sd_event_add_exit
</refname>
25 <refname>sd_event_handler_t
</refname>
27 <refpurpose>Add static event sources to an event loop
</refpurpose>
32 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
34 <funcsynopsisinfo><token>typedef
</token> struct sd_event_source sd_event_source;
</funcsynopsisinfo>
37 <funcdef>typedef int (*
<function>sd_event_handler_t
</function>)
</funcdef>
38 <paramdef>sd_event_source *
<parameter>s
</parameter></paramdef>
39 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
43 <funcdef>int
<function>sd_event_add_defer
</function></funcdef>
44 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
45 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
46 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
47 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
51 <funcdef>int
<function>sd_event_add_post
</function></funcdef>
52 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
53 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
54 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
55 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
59 <funcdef>int
<function>sd_event_add_exit
</function></funcdef>
60 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
61 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
62 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
63 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
70 <title>Description
</title>
72 <para>These three functions add new static event sources to an
73 event loop. The event loop object is specified in the
74 <parameter>event
</parameter> parameter, the event source object is
75 returned in the
<parameter>source
</parameter> parameter. The event
76 sources are enabled statically and will
"fire" when the event loop
77 is run and the conditions described below are met. The handler
78 function will be passed the
<parameter>userdata
</parameter>
79 pointer, which may be chosen freely by the caller.
</para>
81 <para><function>sd_event_add_defer()
</function> adds a new event
82 source that will be dispatched instantly, before the event loop
83 goes to sleep again and waits for new events. By default, the
84 handler will be called once
85 (
<constant>SD_EVENT_ONESHOT
</constant>). Note that if the event
86 source is set to
<constant>SD_EVENT_ON
</constant> the event loop
87 will never go to sleep again, but continuously call the handler,
88 possibly interleaved with other event sources.
</para>
90 <para><function>sd_event_add_post()
</function> adds a new event
91 source that is run before the event loop will sleep and wait
92 for new events, but only after at least one other non-post event
93 source was dispatched. By default, the source is enabled
94 permanently (
<constant>SD_EVENT_ON
</constant>). Note that this
95 event source type will still allow the event loop to go to sleep
96 again, even if set to
<constant>SD_EVENT_ON
</constant>, as long as
97 no other event source is ever triggered.
</para>
99 <para><function>sd_event_add_exit()
</function> adds a new event
100 source that will be dispatched when the event loop is terminated
101 with
<citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
104 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
105 function may be used to enable the event source permanently
106 (
<constant>SD_EVENT_ON
</constant>) or to make it fire just once
107 (
<constant>SD_EVENT_ONESHOT
</constant>).
</para>
109 <para>If the handler function returns a negative error code, it
110 will be disabled after the invocation, even if the
111 <constant>SD_EVENT_ON
</constant> mode was requested before.
</para>
113 <para>To destroy an event source object use
114 <citerefentry><refentrytitle>sd_event_source_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
115 but note that the event source is only removed from the event loop
116 when all references to the event source are dropped. To make sure
117 an event source does not fire anymore, even when there's still a
118 reference to it kept, consider setting the event source to
119 <constant>SD_EVENT_OFF
</constant> with
120 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
122 <para>If the second parameter of these functions is passed as
123 NULL no reference to the event source object is returned. In this
124 case the event source is considered
"floating", and will be
125 destroyed implicitly when the event loop itself is
130 <title>Return Value
</title>
132 <para>On success, these functions return
0 or a positive
133 integer. On failure, they return a negative errno-style error
138 <title>Errors
</title>
140 <para>Returned errors may indicate the following problems:
</para>
144 <term><constant>-ENOMEM
</constant></term>
146 <listitem><para>Not enough memory to allocate an object.
</para></listitem>
150 <term><constant>-EINVAL
</constant></term>
152 <listitem><para>An invalid argument has been passed.
</para></listitem>
156 <term><constant>-ESTALE
</constant></term>
158 <listitem><para>The event loop is already terminated.
</para></listitem>
162 <term><constant>-ECHILD
</constant></term>
164 <listitem><para>The event loop has been created in a different process.
</para></listitem>
170 <xi:include href=
"libsystemd-pkgconfig.xml" />
173 <title>See Also
</title>
176 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
178 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
179 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
180 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
186 <citerefentry><refentrytitle>sd_event_source_set_priority
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
187 <citerefentry><refentrytitle>sd_event_source_set_userdata
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
188 <citerefentry><refentrytitle>sd_event_source_set_description
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
189 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>