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