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">
6 This file is part of elogind.
8 Copyright 2015 Lennart Poettering
10 elogind is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 elogind is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with elogind; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude">
27 <title>sd_event_source_set_enabled</title>
28 <productname>elogind</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_event_source_set_enabled</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_event_source_set_enabled</refname>
47 <refname>sd_event_source_get_enabled</refname>
48 <refname>SD_EVENT_ON</refname>
49 <refname>SD_EVENT_OFF</refname>
50 <refname>SD_EVENT_ONESHOT</refname>
52 <refpurpose>Enable or disable event sources</refpurpose>
57 <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo>
59 <funcsynopsisinfo><token>enum</token> {
60 <constant>SD_EVENT_OFF</constant> = 0,
61 <constant>SD_EVENT_ON</constant> = 1,
62 <constant>SD_EVENT_ONESHOT</constant> = -1,
66 <funcdef>int <function>sd_event_source_set_enabled</function></funcdef>
67 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
68 <paramdef>int <parameter>enabled</parameter></paramdef>
72 <funcdef>int <function>sd_event_source_get_enabled</function></funcdef>
73 <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
74 <paramdef>int *<parameter>enabled</parameter></paramdef>
81 <title>Description</title>
83 <para><function>sd_event_source_set_enabled()</function> may be
84 used to enable or disable the event source object specified as
85 <parameter>source</parameter>. The <parameter>enabled</parameter>
86 parameter takes one of <constant>SD_EVENT_ON</constant> (to
87 enable), <constant>SD_EVENT_OFF</constant> (to disable) or
88 <constant>SD_EVENT_ONESHOT</constant>. If invoked with
89 <constant>SD_EVENT_ONESHOT</constant> the event source will be
90 enabled but automatically reset to
91 <constant>SD_EVENT_OFF</constant> after the event source was
92 dispatched once.</para>
94 <para>Event sources that are disabled will not result in event
95 loop wakeups and will not be dispatched, until they are enabled
98 <para><function>sd_event_source_get_enabled()</function> may be
99 used to query whether the event source object
100 <parameter>source</parameter> is currently enabled or not. It
101 returns the enablement state in
102 <parameter>enabled</parameter>.</para>
104 <para>Event source objects are enabled when they are first created
106 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
107 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
108 depending on the event source type they are enabled continuously
109 (<constant>SD_EVENT_ON</constant>) or only for a single invocation
110 of the event source handler
111 (<constant>SD_EVENT_ONESHOT</constant>). For details see the
112 respective manual pages.</para>
114 <para>As event source objects stay active and may be dispatched as
115 long as there is at least one reference to them, in many cases it
116 is a good idea to combine a call to
117 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
119 <function>sd_event_source_set_enabled()</function> with
120 <constant>SD_EVENT_OFF</constant>, to ensure the event source is
121 not dispatched again until all other remaining references are dropped.</para>
125 <title>Return Value</title>
127 <para>On success, <function>sd_event_source_set_enabled()</function> and
128 <function>sd_event_source_get_enabled()</function> return a
129 non-negative integer. On failure, they return a negative
130 errno-style error code.</para>
134 <title>Errors</title>
136 <para>Returned errors may indicate the following problems:</para>
140 <term><constant>-EINVAL</constant></term>
142 <listitem><para><parameter>source</parameter> is not a valid
143 pointer to an <structname>sd_event_source</structname>
144 object.</para></listitem>
148 <term><constant>-ENOMEM</constant></term>
150 <listitem><para>Not enough memory.</para></listitem>
154 <term><constant>-ECHILD</constant></term>
156 <listitem><para>The event loop has been created in a different process.</para></listitem>
163 <xi:include href="libelogind-pkgconfig.xml" />
166 <title>See Also</title>
169 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>