man/sd_event_add_defer.xml

   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">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_event_add_defer</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>More text</contrib>
  18         <firstname>Zbigniew</firstname>
  19         <surname>Jędrzejewski-Szmek</surname>
  20         <email>zbyszek@in.waw.pl</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_event_add_defer</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_event_add_defer</refname>
  32     <refname>sd_event_add_post</refname>
  33     <refname>sd_event_add_exit</refname>
  34     <refname>sd_event_handler_t</refname>
  35
  36     <refpurpose>Add static event sources to an event loop</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <funcsynopsis>
  41       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  42
  43       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  44
  45       <funcprototype>
  46         <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
  47         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  48         <paramdef>void *<parameter>userdata</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>int <function>sd_event_add_defer</function></funcdef>
  53         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  54         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  55         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  56         <paramdef>void *<parameter>userdata</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_event_add_post</function></funcdef>
  61         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  62         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  63         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  64         <paramdef>void *<parameter>userdata</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_event_add_exit</function></funcdef>
  69         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  70         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  71         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  72         <paramdef>void *<parameter>userdata</parameter></paramdef>
  73       </funcprototype>
  74
  75     </funcsynopsis>
  76   </refsynopsisdiv>
  77
  78   <refsect1>
  79     <title>Description</title>
  80
  81     <para>These three functions add new static event sources to an
  82     event loop. The event loop object is specified in the
  83     <parameter>event</parameter> parameter, the event source object is
  84     returned in the <parameter>source</parameter> parameter. The event
  85     sources are enabled statically and will "fire" when the event loop
  86     is run and the conditions described below are met. The handler
  87     function will be passed the <parameter>userdata</parameter>
  88     pointer, which may be chosen freely by the caller.</para>
  89
  90     <para><function>sd_event_add_defer()</function> adds a new event
  91     source that will be dispatched instantly, before the event loop
  92     goes to sleep again and waits for new events. By default, the
  93     handler will be called once
  94     (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event
  95     source is set to <constant>SD_EVENT_ON</constant> the event loop
  96     will never go to sleep again, but continuously call the handler,
  97     possibly interleaved with other event sources.</para>
  98
  99     <para><function>sd_event_add_post()</function> adds a new event
 100     source that is run before the event loop will sleep and wait
 101     for new events, but only after at least one other non-post event
 102     source was dispatched. By default, the source is enabled
 103     permanently (<constant>SD_EVENT_ON</constant>). Note that this
 104     event source type will still allow the event loop to go to sleep
 105     again, even if set to <constant>SD_EVENT_ON</constant>, as long as
 106     no other event source is ever triggered.</para>
 107
 108     <para><function>sd_event_add_exit()</function> adds a new event
 109     source that will be dispatched when the event loop is terminated
 110     with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 111
 112     <para>The
 113     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114     function may be used to enable the event source permanently
 115     (<constant>SD_EVENT_ON</constant>) or to make it fire just once
 116     (<constant>SD_EVENT_ONESHOT</constant>).</para>
 117
 118     <para>If the handler function returns a negative error code, it
 119     will be disabled after the invocation, even if the
 120     <constant>SD_EVENT_ON</constant> mode was requested before.</para>
 121
 122     <para>To destroy an event source object use
 123     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 124     but note that the event source is only removed from the event loop
 125     when all references to the event source are dropped. To make sure
 126     an event source does not fire anymore, even when there's still a
 127     reference to it kept, consider setting the event source to
 128     <constant>SD_EVENT_OFF</constant> with
 129     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 130
 131     <para>If the second parameter of these functions is passed as
 132     NULL no reference to the event source object is returned. In this
 133     case the event source is considered "floating", and will be
 134     destroyed implicitly when the event loop itself is
 135     destroyed.</para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Return Value</title>
 140
 141     <para>On success, these functions return 0 or a positive
 142     integer. On failure, they return a negative errno-style error
 143     code.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Errors</title>
 148
 149     <para>Returned errors may indicate the following problems:</para>
 150
 151     <variablelist>
 152       <varlistentry>
 153         <term><constant>-ENOMEM</constant></term>
 154
 155         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><constant>-EINVAL</constant></term>
 160
 161         <listitem><para>An invalid argument has been passed.</para></listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><constant>-ESTALE</constant></term>
 166
 167         <listitem><para>The event loop is already terminated.</para></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><constant>-ECHILD</constant></term>
 172
 173         <listitem><para>The event loop has been created in a different process.</para></listitem>
 174       </varlistentry>
 175
 176     </variablelist>
 177   </refsect1>
 178
 179   <xi:include href="libsystemd-pkgconfig.xml" />
 180
 181   <refsect1>
 182     <title>See Also</title>
 183
 184     <para>
 185       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 196       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 197       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 198       <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 199     </para>
 200   </refsect1>
 201
 202 </refentry>