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 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2015 Lennart Poettering
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"sd_event_source_set_enabled" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
29 <title>sd_event_source_set_enabled
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Lennart
</firstname>
36 <surname>Poettering
</surname>
37 <email>lennart@poettering.net
</email>
43 <refentrytitle>sd_event_source_set_enabled
</refentrytitle>
44 <manvolnum>3</manvolnum>
48 <refname>sd_event_source_set_enabled
</refname>
49 <refname>sd_event_source_get_enabled
</refname>
50 <refname>SD_EVENT_ON
</refname>
51 <refname>SD_EVENT_OFF
</refname>
52 <refname>SD_EVENT_ONESHOT
</refname>
54 <refpurpose>Enable or disable event sources
</refpurpose>
59 <funcsynopsisinfo>#include
<systemd/sd-event.h
></funcsynopsisinfo>
61 <funcsynopsisinfo><token>enum
</token> {
62 <constant>SD_EVENT_OFF
</constant> =
0,
63 <constant>SD_EVENT_ON
</constant> =
1,
64 <constant>SD_EVENT_ONESHOT
</constant> = -
1,
68 <funcdef>int
<function>sd_event_source_set_enabled
</function></funcdef>
69 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
70 <paramdef>int
<parameter>enabled
</parameter></paramdef>
74 <funcdef>int
<function>sd_event_source_get_enabled
</function></funcdef>
75 <paramdef>sd_event_source *
<parameter>source
</parameter></paramdef>
76 <paramdef>int *
<parameter>enabled
</parameter></paramdef>
83 <title>Description
</title>
85 <para><function>sd_event_source_set_enabled()
</function> may be
86 used to enable or disable the event source object specified as
87 <parameter>source
</parameter>. The
<parameter>enabled
</parameter>
88 parameter takes one of
<constant>SD_EVENT_ON
</constant> (to
89 enable),
<constant>SD_EVENT_OFF
</constant> (to disable) or
90 <constant>SD_EVENT_ONESHOT
</constant>. If invoked with
91 <constant>SD_EVENT_ONESHOT
</constant> the event source will be
92 enabled but automatically reset to
93 <constant>SD_EVENT_OFF
</constant> after the event source was
94 dispatched once.
</para>
96 <para>Event sources that are disabled will not result in event
97 loop wakeups and will not be dispatched, until they are enabled
100 <para><function>sd_event_source_get_enabled()
</function> may be
101 used to query whether the event source object
102 <parameter>source
</parameter> is currently enabled or not. It
103 returns the enablement state in
104 <parameter>enabled
</parameter>.
</para>
106 <para>Event source objects are enabled when they are first created
108 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
109 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
110 depending on the event source type they are enabled continuously
111 (
<constant>SD_EVENT_ON
</constant>) or only for a single invocation
112 of the event source handler
113 (
<constant>SD_EVENT_ONESHOT
</constant>). For details see the
114 respective manual pages.
</para>
116 <para>As event source objects stay active and may be dispatched as
117 long as there is at least one reference to them, in many cases it
118 is a good idea to combine a call to
119 <citerefentry><refentrytitle>sd_event_source_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
121 <function>sd_event_source_set_enabled()
</function> with
122 <constant>SD_EVENT_OFF
</constant>, to ensure the event source is
123 not dispatched again until all other remaining references are dropped.
</para>
127 <title>Return Value
</title>
129 <para>On success,
<function>sd_event_source_set_enabled()
</function> and
130 <function>sd_event_source_get_enabled()
</function> return a
131 non-negative integer. On failure, they return a negative
132 errno-style error code.
</para>
136 <title>Errors
</title>
138 <para>Returned errors may indicate the following problems:
</para>
142 <term><constant>-EINVAL
</constant></term>
144 <listitem><para><parameter>source
</parameter> is not a valid
145 pointer to an
<structname>sd_event_source
</structname>
146 object.
</para></listitem>
150 <term><constant>-ENOMEM
</constant></term>
152 <listitem><para>Not enough memory.
</para></listitem>
156 <term><constant>-ECHILD
</constant></term>
158 <listitem><para>The event loop has been created in a different process.
</para></listitem>
165 <xi:include href=
"libsystemd-pkgconfig.xml" />
168 <title>See Also
</title>
171 <citerefentry><refentrytitle>sd-event
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_event_add_io
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_event_add_time
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_event_add_child
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175 <citerefentry><refentrytitle>sd_event_add_signal
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
176 <citerefentry><refentrytitle>sd_event_add_defer
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>sd_event_source_unref
</refentrytitle><manvolnum>3</manvolnum></citerefentry>