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