2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_event_source_set_prepare" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_event_source_set_prepare
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_event_source_set_prepare
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_event_source_set_prepare
</refname>
24 <refpurpose>Set a preparation callback for event sources
</refpurpose>
29 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
32 <funcdef>int
<function>sd_event_source_set_prepare
</function></funcdef>
33 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
34 <paramdef>sd_event_handler_t
<parameter>callback
</parameter></paramdef>
38 <funcdef>typedef int (*
<function>sd_event_handler_t
</function>)
</funcdef>
39 <paramdef>sd_event_source *
<parameter>s
</parameter></paramdef>
40 <paramdef>void *
<parameter>userdata
</parameter></paramdef>
47 <title>Description
</title>
49 <para><function>sd_event_source_set_prepare()
</function> may be
50 used to set a preparation callback for the event source object
51 specified as
<parameter>source
</parameter>. The callback function
52 specified as
<parameter>callback
</parameter> will be invoked
53 immediately before the event loop goes to sleep to wait for
54 incoming events. It is invoked with the user data pointer passed
55 when the event source was created. The event source will be disabled
56 if the callback function returns a negative error code. The callback
57 function may be used to reconfigure the precise events to wait for.
58 If the
<parameter>callback
</parameter> parameter is passed as NULL
59 the callback function is reset.
</para>
61 <para>Event source objects have no preparation callback associated
62 when they are first created with calls such as
63 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
64 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
65 callback functions are supported for all event source types with
66 the exception of those created with
67 <citerefentry><refentrytitle>sd_event_add_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
68 callback functions are dispatched in the order indicated by the
69 event source's priority field, as set with
70 <citerefentry><refentrytitle>sd_event_source_set_priority
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
71 callbacks of disabled event sources (see
72 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
73 are not invoked.
</para>
77 <title>Return Value
</title>
80 <function>sd_event_source_set_prepare()
</function> returns a
81 non-negative integer. On failure, it returns a negative
82 errno-style error code.
</para>
88 <para>Returned errors may indicate the following problems:
</para>
92 <term><constant>-EINVAL
</constant></term>
94 <listitem><para><parameter>source
</parameter> is not a valid
95 pointer to an
<structname>sd_event_source
</structname>
96 object.
</para></listitem>
100 <term><constant>-ESTALE
</constant></term>
102 <listitem><para>The event loop is already terminated.
</para></listitem>
106 <term><constant>-ENOMEM
</constant></term>
108 <listitem><para>Not enough memory.
</para></listitem>
112 <term><constant>-ECHILD
</constant></term>
114 <listitem><para>The event loop has been created in a different process.
</para></listitem>
119 <term><constant>-EDOM
</constant></term>
121 <listitem><para>The specified event source has been created
123 <citerefentry><refentrytitle>sd_event_add_exit
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para></listitem>
130 <xi:include href=
"libsystemd-pkgconfig.xml" />
133 <title>See Also
</title>
136 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
137 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
140 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
141 <citerefentry><refentrytitle>sd_event_add_inotify
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
142 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
143 <citerefentry><refentrytitle>sd_event_source_set_enabled
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
144 <citerefentry><refentrytitle>sd_event_source_set_priority
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
145 <citerefentry><refentrytitle>sd_event_source_set_userdata
</refentrytitle><manvolnum>3</manvolnum></citerefentry>