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