man/sd_event_add_defer.xml

   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+ -->
   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 &lt;systemd/sd-event.h&gt;</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
  70     event loop. The event loop object is specified in the
  71     <parameter>event</parameter> parameter, the event source object is
  72     returned in the <parameter>source</parameter> parameter. The event
  73     sources are enabled statically and will "fire" when the event loop
  74     is run and the conditions described below are met. The handler
  75     function will be passed the <parameter>userdata</parameter>
  76     pointer, which may be chosen freely by the caller.</para>
  77
  78     <para><function>sd_event_add_defer()</function> adds a new event
  79     source that will be dispatched instantly, before the event loop
  80     goes to sleep again and waits for new events. By default, the
  81     handler will be called once
  82     (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event
  83     source is set to <constant>SD_EVENT_ON</constant> the event loop
  84     will never go to sleep again, but continuously call the handler,
  85     possibly interleaved with other event sources.</para>
  86
  87     <para><function>sd_event_add_post()</function> adds a new event
  88     source that is run before the event loop will sleep and wait
  89     for new events, but only after at least one other non-post event
  90     source was dispatched. By default, the source is enabled
  91     permanently (<constant>SD_EVENT_ON</constant>). Note that this
  92     event source type will still allow the event loop to go to sleep
  93     again, even if set to <constant>SD_EVENT_ON</constant>, as long as
  94     no other event source is ever triggered.</para>
  95
  96     <para><function>sd_event_add_exit()</function> adds a new event
  97     source that will be dispatched when the event loop is terminated
  98     with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  99
 100     <para>The
 101     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 102     function may be used to enable the event source permanently
 103     (<constant>SD_EVENT_ON</constant>) or to make it fire just once
 104     (<constant>SD_EVENT_ONESHOT</constant>).</para>
 105
 106     <para>If the handler function returns a negative error code, it
 107     will be disabled after the invocation, even if the
 108     <constant>SD_EVENT_ON</constant> mode was requested before.</para>
 109
 110     <para>To destroy an event source object use
 111     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 112     but note that the event source is only removed from the event loop
 113     when all references to the event source are dropped. To make sure
 114     an event source does not fire anymore, even when there's still a
 115     reference to it kept, consider setting the event source to
 116     <constant>SD_EVENT_OFF</constant> with
 117     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 118
 119     <para>If the second parameter of these functions is passed as
 120     NULL no reference to the event source object is returned. In this
 121     case the event source is considered "floating", and will be
 122     destroyed implicitly when the event loop itself is
 123     destroyed.</para>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>Return Value</title>
 128
 129     <para>On success, these functions return 0 or a positive
 130     integer. On failure, they return a negative errno-style error
 131     code.</para>
 132
 133     <refsect2>
 134       <title>Errors</title>
 135
 136       <para>Returned errors may indicate the following problems:</para>
 137
 138       <variablelist>
 139         <varlistentry>
 140           <term><constant>-ENOMEM</constant></term>
 141
 142           <listitem><para>Not enough memory to allocate an object.</para></listitem>
 143         </varlistentry>
 144
 145         <varlistentry>
 146           <term><constant>-EINVAL</constant></term>
 147
 148           <listitem><para>An invalid argument has been passed.</para></listitem>
 149         </varlistentry>
 150
 151         <varlistentry>
 152           <term><constant>-ESTALE</constant></term>
 153
 154           <listitem><para>The event loop is already terminated.</para></listitem>
 155         </varlistentry>
 156
 157         <varlistentry>
 158           <term><constant>-ECHILD</constant></term>
 159
 160           <listitem><para>The event loop has been created in a different process.</para></listitem>
 161         </varlistentry>
 162
 163       </variablelist>
 164     </refsect2>
 165   </refsect1>
 166
 167   <xi:include href="libsystemd-pkgconfig.xml" />
 168
 169   <refsect1>
 170     <title>See Also</title>
 171
 172     <para>
 173       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 174       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 187     </para>
 188   </refsect1>
 189
 190 </refentry>