man/sd_event_source_set_enabled.xml

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