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+
8 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
13 <refentry id=
"sd_event_add_defer" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
16 <title>sd_event_add_defer
</title>
17 <productname>systemd
</productname>
21 <contrib>More text
</contrib>
22 <firstname>Zbigniew
</firstname>
23 <surname>Jędrzejewski-Szmek
</surname>
24 <email>zbyszek@in.waw.pl
</email>
30 <refentrytitle>sd_event_add_defer
</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_event_add_defer
</refname>
36 <refname>sd_event_add_post
</refname>
37 <refname>sd_event_add_exit
</refname>
38 <refname>sd_event_handler_t
</refname>
40 <refpurpose>Add static event sources to an event loop
</refpurpose>
45 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
47 <funcsynopsisinfo><token>typedef
</token> struct sd_event_source sd_event_source;
</funcsynopsisinfo>
50 <funcdef>typedef int (*
<function>sd_event_handler_t
</function>)
</funcdef>
51 <paramdef>sd_event_source *
<parameter>s
</parameter></paramdef>
52 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
56 <funcdef>int
<function>sd_event_add_defer
</function></funcdef>
57 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
58 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
59 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
60 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
64 <funcdef>int
<function>sd_event_add_post
</function></funcdef>
65 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
66 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
67 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
68 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
72 <funcdef>int
<function>sd_event_add_exit
</function></funcdef>
73 <paramdef>sd_event *
<parameter>event
</parameter></paramdef>
74 <paramdef>sd_event_source **
<parameter>source
</parameter></paramdef>
75 <paramdef>sd_event_handler_t
<parameter>handler
</parameter></paramdef>
76 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
83 <title>Description
</title>
85 <para>These three functions add new static event sources to an
86 event loop. The event loop object is specified in the
87 <parameter>event
</parameter> parameter, the event source object is
88 returned in the
<parameter>source
</parameter> parameter. The event
89 sources are enabled statically and will
"fire" when the event loop
90 is run and the conditions described below are met. The handler
91 function will be passed the
<parameter>userdata
</parameter>
92 pointer, which may be chosen freely by the caller.
</para>
94 <para><function>sd_event_add_defer()
</function> adds a new event
95 source that will be dispatched instantly, before the event loop
96 goes to sleep again and waits for new events. By default, the
97 handler will be called once
98 (
<constant>SD_EVENT_ONESHOT
</constant>). Note that if the event
99 source is set to
<constant>SD_EVENT_ON
</constant> the event loop
100 will never go to sleep again, but continuously call the handler,
101 possibly interleaved with other event sources.
</para>
103 <para><function>sd_event_add_post()
</function> adds a new event
104 source that is run before the event loop will sleep and wait
105 for new events, but only after at least one other non-post event
106 source was dispatched. By default, the source is enabled
107 permanently (
<constant>SD_EVENT_ON
</constant>). Note that this
108 event source type will still allow the event loop to go to sleep
109 again, even if set to
<constant>SD_EVENT_ON
</constant>, as long as
110 no other event source is ever triggered.
</para>
112 <para><function>sd_event_add_exit()
</function> adds a new event
113 source that will be dispatched when the event loop is terminated
114 with
<citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</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>).
</para>
122 <para>If the handler function returns a negative error code, it
123 will be disabled after the invocation, even if the
124 <constant>SD_EVENT_ON
</constant> mode was requested before.
</para>
126 <para>To destroy an event source object use
127 <citerefentry><refentrytitle>sd_event_source_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
128 but note that the event source is only removed from the event loop
129 when all references to the event source are dropped. To make sure
130 an event source does not fire anymore, even when there's still a
131 reference to it kept, consider setting the event source to
132 <constant>SD_EVENT_OFF
</constant> with
133 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
135 <para>If the second parameter of these functions is passed as
136 NULL no reference to the event source object is returned. In this
137 case the event source is considered
"floating", and will be
138 destroyed implicitly when the event loop itself is
143 <title>Return Value
</title>
145 <para>On success, these functions return
0 or a positive
146 integer. On failure, they return a negative errno-style error
151 <title>Errors
</title>
153 <para>Returned errors may indicate the following problems:
</para>
157 <term><constant>-ENOMEM
</constant></term>
159 <listitem><para>Not enough memory to allocate an object.
</para></listitem>
163 <term><constant>-EINVAL
</constant></term>
165 <listitem><para>An invalid argument has been passed.
</para></listitem>
169 <term><constant>-ESTALE
</constant></term>
171 <listitem><para>The event loop is already terminated.
</para></listitem>
175 <term><constant>-ECHILD
</constant></term>
177 <listitem><para>The event loop has been created in a different process.
</para></listitem>
183 <xi:include href=
"libsystemd-pkgconfig.xml" />
186 <title>See Also
</title>
189 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
190 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
191 <citerefentry><refentrytitle>sd_event_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
192 <citerefentry><refentrytitle>sd_event_now
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
193 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
194 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd_event_source_set_priority
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_event_source_set_userdata
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
201 <citerefentry><refentrytitle>sd_event_source_set_description
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
202 <citerefentry><refentrytitle>sd_event_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>