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