1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_source_set_enabled</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_source_set_enabled</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_source_set_enabled</refname> 20 <refname>sd_event_source_get_enabled</refname> 21 <refname>SD_EVENT_ON</refname> 22 <refname>SD_EVENT_OFF</refname> 23 <refname>SD_EVENT_ONESHOT</refname> 24 25 <refpurpose>Enable or disable event sources</refpurpose> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <funcsynopsis> 30 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 31 32 <funcsynopsisinfo><token>enum</token> { 33 <constant>SD_EVENT_OFF</constant> = 0, 34 <constant>SD_EVENT_ON</constant> = 1, 35 <constant>SD_EVENT_ONESHOT</constant> = -1, 36};</funcsynopsisinfo> 37 38 <funcprototype> 39 <funcdef>int <function>sd_event_source_set_enabled</function></funcdef> 40 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 41 <paramdef>int <parameter>enabled</parameter></paramdef> 42 </funcprototype> 43 44 <funcprototype> 45 <funcdef>int <function>sd_event_source_get_enabled</function></funcdef> 46 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 47 <paramdef>int *<parameter>enabled</parameter></paramdef> 48 </funcprototype> 49 50 </funcsynopsis> 51 </refsynopsisdiv> 52 53 <refsect1> 54 <title>Description</title> 55 56 <para><function>sd_event_source_set_enabled()</function> may be 57 used to enable or disable the event source object specified as 58 <parameter>source</parameter>. The <parameter>enabled</parameter> 59 parameter takes one of <constant>SD_EVENT_ON</constant> (to 60 enable), <constant>SD_EVENT_OFF</constant> (to disable) or 61 <constant>SD_EVENT_ONESHOT</constant>. If invoked with 62 <constant>SD_EVENT_ONESHOT</constant> the event source will be 63 enabled but automatically reset to 64 <constant>SD_EVENT_OFF</constant> after the event source was 65 dispatched once.</para> 66 67 <para>Event sources that are disabled will not result in event 68 loop wakeups and will not be dispatched, until they are enabled 69 again.</para> 70 71 <para><function>sd_event_source_get_enabled()</function> may be 72 used to query whether the event source object 73 <parameter>source</parameter> is currently enabled or not. It 74 returns the enablement state (one of <constant>SD_EVENT_ON</constant>, 75 <constant>SD_EVENT_OFF</constant>, <constant>SD_EVENT_ONESHOT</constant>) 76 in <parameter>enabled</parameter>, if it is not <constant>NULL</constant>. 77 It also returns true if the event source is not disabled.</para> 78 79 <para>Event source objects are enabled when they are first created 80 with calls such as 81 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 82 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However, 83 depending on the event source type they are enabled continuously 84 (<constant>SD_EVENT_ON</constant>) or only for a single invocation 85 of the event source handler 86 (<constant>SD_EVENT_ONESHOT</constant>). For details see the 87 respective manual pages.</para> 88 89 <para>As event source objects stay active and may be dispatched as 90 long as there is at least one reference to them, in many cases it 91 is a good idea to combine a call to 92 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> 93 with a prior call to 94 <function>sd_event_source_set_enabled()</function> with 95 <constant>SD_EVENT_OFF</constant>, to ensure the event source is 96 not dispatched again until all other remaining references are dropped.</para> 97 </refsect1> 98 99 <refsect1> 100 <title>Return Value</title> 101 102 <para>On success, <function>sd_event_source_set_enabled()</function> returns a non-negative 103 integer. <function>sd_event_source_get_enabled()</function> returns zero if the source is disabled 104 (<constant>SD_EVENT_OFF</constant>) and a positive integer otherwise. On failure, they return a negative 105 errno-style error code.</para> 106 107 <refsect2> 108 <title>Errors</title> 109 110 <para>Returned errors may indicate the following problems:</para> 111 112 <variablelist> 113 <varlistentry> 114 <term><constant>-EINVAL</constant></term> 115 116 <listitem><para><parameter>source</parameter> is not a valid pointer to an 117 <structname>sd_event_source</structname> object.</para></listitem> 118 </varlistentry> 119 120 <varlistentry> 121 <term><constant>-ENOMEM</constant></term> 122 123 <listitem><para>Not enough memory.</para></listitem> 124 </varlistentry> 125 126 <varlistentry> 127 <term><constant>-ECHILD</constant></term> 128 129 <listitem><para>The event loop has been created in a different process.</para></listitem> 130 131 </varlistentry> 132 133 </variablelist> 134 </refsect2> 135 </refsect1> 136 137 <xi:include href="libsystemd-pkgconfig.xml" /> 138 139 <refsect1> 140 <title>See Also</title> 141 142 <para> 143 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 144 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 145 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 146 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 147 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 148 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 149 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 150 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 151 <citerefentry><refentrytitle>sd_event_source_set_ratelimit</refentrytitle><manvolnum>3</manvolnum></citerefentry> 152 </para> 153 </refsect1> 154 155</refentry> 156