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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_event_add_defer">
  28
  29   <refentryinfo>
  30     <title>sd_event_add_defer</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>More text</contrib>
  36         <firstname>Zbigniew</firstname>
  37         <surname>Jędrzejewski-Szmek</surname>
  38         <email>zbyszek@in.waw.pl</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_event_add_defer</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_event_add_defer</refname>
  50     <refname>sd_event_add_post</refname>
  51     <refname>sd_event_add_exit</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-bus.h&gt;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_event_add_defer</function></funcdef>
  62         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  63         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  64         <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef>
  65         <paramdef>void *<parameter>userdata</parameter></paramdef>
  66       </funcprototype>
  67
  68       <funcprototype>
  69         <funcdef>int <function>sd_event_add_post</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_exit</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>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
  86         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  87         <paramdef>void *<parameter>userdata</parameter></paramdef>
  88       </funcprototype>
  89
  90     </funcsynopsis>
  91   </refsynopsisdiv>
  92
  93   <refsect1>
  94     <title>Description</title>
  95
  96     <para>Those three functions add new event sources to an event loop
  97     object. The event loop is specified in
  98     <parameter>event</parameter>, the event source is returned in the
  99     <parameter>source</parameter> parameter. The event sources are
 100     enabled statically and will "fire" when the event loop is run and
 101     the conditions described below are met. The handler function will
 102     be passed the <parameter>userdata</parameter> pointer, which may
 103     be chosen freely by the caller.</para>
 104
 105     <para><function>sd_event_add_defer()</function> adds a new event
 106     source that will "fire" the next time the event loop is run. By
 107     default, the handler will be called once
 108     (<constant>SD_EVENT_ONESHOT</constant>).</para>
 109
 110     <para><function>sd_event_add_post()</function> adds a new event
 111     source that will "fire" if any event handlers are invoked whenever
 112     the event loop is run. By default, the source is enabled
 113     permanently (<constant>SD_EVENT_ON</constant>).</para>
 114
 115     <para><function>sd_event_add_exit()</function> adds a new event
 116     source that will "fire" when the event loop is terminated
 117     with <function>sd_event_exit()</function>.</para>
 118
 119     <para>The
 120     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 121     function may be used to enable the event source permanently
 122     (<constant>SD_EVENT_ON</constant>) or to make it fire just once
 123     (<constant>SD_EVENT_ONESHOT</constant>). If the handler function
 124     returns a negative error code, it will be disabled after the
 125     invocation, even if <constant>SD_EVENT_ON</constant> mode is
 126     set.</para>
 127   </refsect1>
 128
 129   <refsect1>
 130     <title>Return Value</title>
 131
 132     <para>On success, this functions return 0 or a positive
 133     integer. On failure, they return a negative errno-style error
 134     code.</para>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Errors</title>
 139
 140     <para>Returned errors may indicate the following problems:</para>
 141
 142     <variablelist>
 143       <varlistentry>
 144         <term><constant>-ENOMEM</constant></term>
 145
 146         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><constant>-EINVAL</constant></term>
 151
 152         <listitem><para>An invalid argument has been passed.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><constant>-ESTALE</constant></term>
 157
 158         <listitem><para>The event loop is already terminated.</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><constant>-ECHILD</constant></term>
 163
 164         <listitem><para>The event loop has been created in a different process.</para></listitem>
 165       </varlistentry>
 166
 167     </variablelist>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>Notes</title>
 172
 173     <para>Functions described here are available as a shared library,
 174     which can be compiled and linked to with the
 175     <constant>libsystemd</constant> <citerefentry
 176     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 177     file.</para>
 178   </refsect1>
 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_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 191     </para>
 192   </refsect1>
 193
 194 </refentry>