man/sd_event_source_set_enabled.xml

   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 &lt;systemd/sd-event.h&gt;</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 used to enable or disable the event
  57     source object specified as <parameter>source</parameter>. The <parameter>enabled</parameter> parameter
  58     takes one of <constant>SD_EVENT_ON</constant> (to enable), <constant>SD_EVENT_OFF</constant> (to disable)
  59     or <constant>SD_EVENT_ONESHOT</constant>. If invoked with <constant>SD_EVENT_ONESHOT</constant> the event
  60     source will be enabled but automatically reset to <constant>SD_EVENT_OFF</constant> after one dispatch.
  61     For <constant>SD_EVENT_OFF</constant>, the event source <parameter>source</parameter> may be
  62     <constant>NULL</constant>, in which case the function does nothing. Otherwise,
  63     <parameter>source</parameter> must be a valid pointer to an <structname>sd_event_source</structname>
  64     object.</para>
  65
  66     <para>Event sources that are disabled will not result in event
  67     loop wakeups and will not be dispatched, until they are enabled
  68     again.</para>
  69
  70     <para><function>sd_event_source_get_enabled()</function> may be used to query whether the event source
  71     object <parameter>source</parameter> is currently enabled or not. If both the
  72     <parameter>source</parameter> and the output parameter <parameter>enabled</parameter> are
  73     <constant>NULL</constant>, this function returns false. Otherwise, <parameter>source</parameter> must be
  74     a valid pointer to an <structname>sd_event_source</structname> object. If the output parameter
  75     <parameter>enabled</parameter> is not <constant>NULL</constant>, it is set to the enablement state (one
  76     of <constant>SD_EVENT_ON</constant>, <constant>SD_EVENT_OFF</constant>,
  77     <constant>SD_EVENT_ONESHOT</constant>). The function also returns true if the event source is not
  78     disabled.</para>
  79
  80     <para>Event source objects are enabled when they are first created
  81     with calls such as
  82     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  83     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
  84     depending on the event source type they are enabled continuously
  85     (<constant>SD_EVENT_ON</constant>) or only for a single invocation
  86     of the event source handler
  87     (<constant>SD_EVENT_ONESHOT</constant>). For details see the
  88     respective manual pages.</para>
  89
  90     <para>As event source objects stay active and may be dispatched as
  91     long as there is at least one reference to them, in many cases it
  92     is a good idea to combine a call to
  93     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  94     with a prior call to
  95     <function>sd_event_source_set_enabled()</function> with
  96     <constant>SD_EVENT_OFF</constant>, to ensure the event source is
  97     not dispatched again until all other remaining references are dropped.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Return Value</title>
 102
 103     <para>On success, <function>sd_event_source_set_enabled()</function> returns a non-negative
 104     integer. <function>sd_event_source_get_enabled()</function> returns zero if the source is disabled
 105     (<constant>SD_EVENT_OFF</constant>) and a positive integer otherwise. On failure, they return a negative
 106     errno-style error code.</para>
 107
 108     <refsect2>
 109       <title>Errors</title>
 110
 111       <para>Returned errors may indicate the following problems:</para>
 112
 113       <variablelist>
 114         <varlistentry>
 115           <term><constant>-EINVAL</constant></term>
 116
 117           <listitem><para><parameter>source</parameter> is not a valid pointer to an
 118           <structname>sd_event_source</structname> object.</para></listitem>
 119         </varlistentry>
 120
 121         <varlistentry>
 122           <term><constant>-ENOMEM</constant></term>
 123
 124           <listitem><para>Not enough memory.</para></listitem>
 125         </varlistentry>
 126
 127         <varlistentry>
 128           <term><constant>-ECHILD</constant></term>
 129
 130           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 131
 132         </varlistentry>
 133
 134       </variablelist>
 135     </refsect2>
 136   </refsect1>
 137
 138   <xi:include href="libsystemd-pkgconfig.xml" />
 139
 140   <refsect1>
 141     <title>History</title>
 142     <para><function>sd_event_source_set_enabled()</function> and
 143     <function>sd_event_source_get_enabled()</function> were added in version 229.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>See Also</title>
 148
 149     <para>
 150       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 155       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 156       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 157       <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 158       <citerefentry><refentrytitle>sd_event_source_set_ratelimit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 159     </para>
 160   </refsect1>
 161
 162 </refentry>