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