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+ -->
   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
  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     </para>
 152   </refsect1>
 153
 154 </refentry>