<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude">

<refentryinfo>

<title>sd_event_source_set_prepare</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_event_source_set_prepare</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_event_source_set_prepare</refname>

<refpurpose>Set a preparation callback for event sources</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_event_source_set_prepare</function></funcdef>

<paramdef>sd_event_source *<parameter>source</parameter></paramdef>

<paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>

<paramdef>sd_event_source *<parameter>s</parameter></paramdef>

<paramdef>void *<parameter>userdata</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_event_source_set_prepare()</function> may be

used to set a preparation callback for the event source object

specified as <parameter>source</parameter>. The callback function

specified as <parameter>callback</parameter> will be invoked

immediately before the event loop goes to sleep to wait for

incoming events. It is invoked with the user data pointer passed

when the event source was created. The callback function may be

used to reconfigure the precise events to wait for. If the

<parameter>callback</parameter> parameter is passed as NULL the

callback function is reset. </para>

<para>Event source objects have no preparation callback associated

when they are first created with calls such as

<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation

callback functions are supported for all event source types with

the exception of those created with

<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation

callback functions are dispatched in the order indicated by the

event source's priority field, as set with

<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation

callbacks of disabled event sources (see

<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>)

are not invoked.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On success,

<function>sd_event_source_set_prepare()</function> returns a

non-negative integer. On failure, it returns a negative

errno-style error code.</para>

</refsect1>

<refsect1>

<title>Errors</title>

<para>Returned errors may indicate the following problems:</para>

<variablelist>

<varlistentry>

<term><constant>-EINVAL</constant></term>

<listitem><para><parameter>source</parameter> is not a valid

pointer to an <structname>sd_event_source</structname>

object.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ESTALE</constant></term>

<listitem><para>The event loop is already terminated.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ENOMEM</constant></term>

<listitem><para>Not enough memory.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ECHILD</constant></term>

<listitem><para>The event loop has been created in a different process.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-EDOM</constant></term>

<listitem><para>The specified event source has been created

with

<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<xi:include href="libsystemd-pkgconfig.xml" />

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>