1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_add_defer</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_add_defer</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_add_defer</refname> 20 <refname>sd_event_add_post</refname> 21 <refname>sd_event_add_exit</refname> 22 <refname>sd_event_handler_t</refname> 23 24 <refpurpose>Add static event sources to an event loop</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <funcsynopsis> 29 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 30 31 <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> 32 33 <funcprototype> 34 <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> 35 <paramdef>sd_event_source *<parameter>s</parameter></paramdef> 36 <paramdef>void *<parameter>userdata</parameter></paramdef> 37 </funcprototype> 38 39 <funcprototype> 40 <funcdef>int <function>sd_event_add_defer</function></funcdef> 41 <paramdef>sd_event *<parameter>event</parameter></paramdef> 42 <paramdef>sd_event_source **<parameter>source</parameter></paramdef> 43 <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> 44 <paramdef>void *<parameter>userdata</parameter></paramdef> 45 </funcprototype> 46 47 <funcprototype> 48 <funcdef>int <function>sd_event_add_post</function></funcdef> 49 <paramdef>sd_event *<parameter>event</parameter></paramdef> 50 <paramdef>sd_event_source **<parameter>source</parameter></paramdef> 51 <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> 52 <paramdef>void *<parameter>userdata</parameter></paramdef> 53 </funcprototype> 54 55 <funcprototype> 56 <funcdef>int <function>sd_event_add_exit</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> 61 </funcprototype> 62 63 </funcsynopsis> 64 </refsynopsisdiv> 65 66 <refsect1> 67 <title>Description</title> 68 69 <para>These three functions add new static event sources to an event loop. The event loop object is 70 specified in the <parameter>event</parameter> parameter, the event source object is returned in the 71 <parameter>source</parameter> parameter. The event sources are enabled statically and will "fire" when 72 the event loop is run and the conditions described below are met.</para> 73 74 <para>The <parameter>handler</parameter> is a function to call or <constant>NULL</constant>. The handler 75 function will be passed the <parameter>userdata</parameter> pointer, which may be chosen freely by the 76 caller. The handler may return negative to signal an error (see below), other return values are 77 ignored. If <parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls 78 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be 79 used.</para> 80 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> 89 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> 98 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> 102 103 <para>The 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> 108 109 <para>If the handler function returns a negative error code, it will either be disabled after the 110 invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the 111 loop to terminate, see 112 <citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 113 </para> 114 115 <para>To destroy an event source object use 116 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 117 but note that the event source is only removed from the event loop 118 when all references to the event source are dropped. To make sure 119 an event source does not fire anymore, even when there's still a 120 reference to it kept, consider setting the event source to 121 <constant>SD_EVENT_OFF</constant> with 122 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 123 124 <para>If the second parameter of these functions is passed as <constant>NULL</constant> no reference to 125 the event source object is returned. In this case the event source is considered "floating", and will be 126 destroyed implicitly when the event loop itself is destroyed.</para> 127 128 <para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_defer()</function> or 129 <function>sd_event_add_post()</function> is <constant>NULL</constant>, and the event source fires, this 130 will be considered a request to exit the event loop. In this case, the <parameter>userdata</parameter> 131 parameter, cast to an integer, is passed as the exit code parameter to 132 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Similar 133 functionality is not available for <function>sd_event_add_exit()</function>, as these types of event 134 sources are only dispatched when exiting anyway.</para> 135 </refsect1> 136 137 <refsect1> 138 <title>Return Value</title> 139 140 <para>On success, these functions return 0 or a positive 141 integer. On failure, they return a negative errno-style error 142 code.</para> 143 144 <refsect2> 145 <title>Errors</title> 146 147 <para>Returned errors may indicate the following problems:</para> 148 149 <variablelist> 150 <varlistentry> 151 <term><constant>-ENOMEM</constant></term> 152 153 <listitem><para>Not enough memory to allocate an object.</para></listitem> 154 </varlistentry> 155 156 <varlistentry> 157 <term><constant>-EINVAL</constant></term> 158 159 <listitem><para>An invalid argument has been passed.</para></listitem> 160 </varlistentry> 161 162 <varlistentry> 163 <term><constant>-ESTALE</constant></term> 164 165 <listitem><para>The event loop is already terminated.</para></listitem> 166 </varlistentry> 167 168 <varlistentry> 169 <term><constant>-ECHILD</constant></term> 170 171 <listitem><para>The event loop has been created in a different process.</para></listitem> 172 </varlistentry> 173 174 </variablelist> 175 </refsect2> 176 </refsect1> 177 178 <xi:include href="libsystemd-pkgconfig.xml" /> 179 180 <refsect1> 181 <title>See Also</title> 182 183 <para> 184 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 185 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 186 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 187 <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 188 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 189 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 190 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 191 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 192 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 193 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 194 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 195 <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 196 <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 197 <citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 198 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> 199 </para> 200 </refsect1> 201 202</refentry> 203