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