man/sd_event_source_set_prepare.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 elogind.
   7
   8   Copyright 2015 Lennart Poettering
   9
  10   elogind 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   elogind 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 elogind; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude">
  25
  26   <refentryinfo>
  27     <title>sd_event_source_set_prepare</title>
  28     <productname>elogind</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_event_source_set_prepare</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_event_source_set_prepare</refname>
  47
  48     <refpurpose>Set a preparation callback for event sources</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <funcsynopsis>
  53       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_event_source_set_prepare</function></funcdef>
  57         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  58         <paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
  63         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  64         <paramdef>void *<parameter>userdata</parameter></paramdef>
  65       </funcprototype>
  66
  67     </funcsynopsis>
  68   </refsynopsisdiv>
  69
  70   <refsect1>
  71     <title>Description</title>
  72
  73     <para><function>sd_event_source_set_prepare()</function> may be
  74     used to set a preparation callback for the event source object
  75     specified as <parameter>source</parameter>. The callback function
  76     specified as <parameter>callback</parameter> will be invoked
  77     immediately before the event loop goes to sleep to wait for
  78     incoming events. It is invoked with the user data pointer passed
  79     when the event source was created. The event source will be disabled
  80     if the callback function returns a negative error code. The callback
  81     function may be used to reconfigure the precise events to wait for.
  82     If the <parameter>callback</parameter> parameter is passed as NULL
  83     the callback function is reset. </para>
  84
  85     <para>Event source objects have no preparation callback associated
  86     when they are first created with calls such as
  87     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  88     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
  89     callback functions are supported for all event source types with
  90     the exception of those created with
  91     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
  92     callback functions are dispatched in the order indicated by the
  93     event source's priority field, as set with
  94     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
  95     callbacks of disabled event sources (see
  96     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
  97     are not invoked.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Return Value</title>
 102
 103     <para>On success,
 104     <function>sd_event_source_set_prepare()</function> returns a
 105     non-negative integer. On failure, it returns a negative
 106     errno-style error code.</para>
 107   </refsect1>
 108
 109   <refsect1>
 110     <title>Errors</title>
 111
 112     <para>Returned errors may indicate the following problems:</para>
 113
 114     <variablelist>
 115       <varlistentry>
 116         <term><constant>-EINVAL</constant></term>
 117
 118         <listitem><para><parameter>source</parameter> is not a valid
 119         pointer to an <structname>sd_event_source</structname>
 120         object.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><constant>-ESTALE</constant></term>
 125
 126         <listitem><para>The event loop is already terminated.</para></listitem>
 127
 128       </varlistentry>
 129       <varlistentry>
 130         <term><constant>-ENOMEM</constant></term>
 131
 132         <listitem><para>Not enough memory.</para></listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><constant>-ECHILD</constant></term>
 137
 138         <listitem><para>The event loop has been created in a different process.</para></listitem>
 139
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><constant>-EDOM</constant></term>
 144
 145         <listitem><para>The specified event source has been created
 146         with
 147         <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 148
 149       </varlistentry>
 150
 151     </variablelist>
 152   </refsect1>
 153
 154   <xi:include href="libelogind-pkgconfig.xml" />
 155
 156   <refsect1>
 157     <title>See Also</title>
 158
 159     <para>
 160       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 161       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 164       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 166       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 167       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 169     </para>
 170   </refsect1>
 171
 172 </refentry>