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