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