b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira This file is part of systemd.
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira Copyright 2015 Lennart Poettering
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira systemd is free software; you can redistribute it and/or modify it
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira under the terms of the GNU Lesser General Public License as published by
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira the Free Software Foundation; either version 2.1 of the License, or
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira (at your option) any later version.
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira systemd is distributed in the hope that it will be useful, but
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira WITHOUT ANY WARRANTY; without even the implied warranty of
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira Lesser General Public License for more details.
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira You should have received a copy of the GNU Lesser General Public License
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira along with systemd; If not, see <http://www.gnu.org/licenses/>.
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira<refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude">
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <refentryinfo>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <authorgroup>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </authorgroup>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </refentryinfo>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <refentrytitle>sd_event_source_set_prepare</refentrytitle>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <refname>sd_event_source_set_prepare</refname>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <refpurpose>Set a preparation callback for event sources</refpurpose>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </refnamediv>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <refsynopsisdiv>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <funcsynopsis>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
158bffeb434c0015e2d6b9e9f15e24a6dc69a493Rafael Ferreira <funcprototype>
158bffeb434c0015e2d6b9e9f15e24a6dc69a493Rafael Ferreira <funcdef>int <function>sd_event_source_set_prepare</function></funcdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </funcprototype>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <funcprototype>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <paramdef>void *<parameter>userdata</parameter></paramdef>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </funcprototype>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </funcsynopsis>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </refsynopsisdiv>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <para><function>sd_event_source_set_prepare()</function> may be
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira used to set a preparation callback for the event source object
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira specified as <parameter>source</parameter>. The callback function
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira specified as <parameter>callback</parameter> will be invoked
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira immediately before the event loop goes to sleep to wait for
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira incoming events. It is invoked with the user data pointer passed
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira when the event source was created. The callback function may be
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira used to reconfigure the precise events to wait for. If the
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <parameter>callback</parameter> parameter is passed as NULL the
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira callback function is reset. </para>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <para>Event source objects have no preparation callback associated
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira when they are first created with calls such as
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira callback functions are supported for all event source types with
158bffeb434c0015e2d6b9e9f15e24a6dc69a493Rafael Ferreira the exception of those created with
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira callback functions are dispatched in the order indicated by the
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira event source's priority field, as set with
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira callbacks of disabled event sources (see
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira are not invoked.</para>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <para>On success,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <function>sd_event_source_set_prepare()</function> returns a
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira non-negative integer. On failure, it returns a negative
158bffeb434c0015e2d6b9e9f15e24a6dc69a493Rafael Ferreira errno-style error code.</para>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <para>Returned errors may indicate the following problems:</para>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <variablelist>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <listitem><para><parameter>source</parameter> is not a valid
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira pointer to an <structname>sd_event_source</structname>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <listitem><para>The event loop is already terminated.</para></listitem>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <listitem><para>Not enough memory.</para></listitem>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <listitem><para>The event loop has been created in a different process.</para></listitem>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <listitem><para>The specified event source has been created
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </varlistentry>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira </variablelist>
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <xi:include href="libsystemd-pkgconfig.xml" />
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
b3e486b8194f238fdb7cdf977cb6943305b34b9cRafael Ferreira <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>