Lennart Poettering
818bf54632
This part of the copyright blurb stems from the GPL use recommendations: https://www.gnu.org/licenses/gpl-howto.en.html The concept appears to originate in times where version control was per file, instead of per tree, and was a way to glue the files together. Ultimately, we nowadays don't live in that world anymore, and this information is entirely useless anyway, as people are very welcome to copy these files into any projects they like, and they shouldn't have to change bits that are part of our copyright header for that. hence, let's just get rid of this old cruft, and shorten our codebase a bit.
167 lines
6.1 KiB
XML
167 lines
6.1 KiB
XML
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
SPDX-License-Identifier: LGPL-2.1+
|
|
|
|
Copyright 2015 Lennart Poettering
|
|
-->
|
|
|
|
<refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>sd_event_source_set_enabled</title>
|
|
<productname>systemd</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Lennart</firstname>
|
|
<surname>Poettering</surname>
|
|
<email>lennart@poettering.net</email>
|
|
</author>
|
|
</authorgroup>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>sd_event_source_set_enabled</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>sd_event_source_set_enabled</refname>
|
|
<refname>sd_event_source_get_enabled</refname>
|
|
<refname>SD_EVENT_ON</refname>
|
|
<refname>SD_EVENT_OFF</refname>
|
|
<refname>SD_EVENT_ONESHOT</refname>
|
|
|
|
<refpurpose>Enable or disable event sources</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo>
|
|
|
|
<funcsynopsisinfo><token>enum</token> {
|
|
<constant>SD_EVENT_OFF</constant> = 0,
|
|
<constant>SD_EVENT_ON</constant> = 1,
|
|
<constant>SD_EVENT_ONESHOT</constant> = -1,
|
|
};</funcsynopsisinfo>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_set_enabled</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>int <parameter>enabled</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>int <function>sd_event_source_get_enabled</function></funcdef>
|
|
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
|
|
<paramdef>int *<parameter>enabled</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><function>sd_event_source_set_enabled()</function> may be
|
|
used to enable or disable the event source object specified as
|
|
<parameter>source</parameter>. The <parameter>enabled</parameter>
|
|
parameter takes one of <constant>SD_EVENT_ON</constant> (to
|
|
enable), <constant>SD_EVENT_OFF</constant> (to disable) or
|
|
<constant>SD_EVENT_ONESHOT</constant>. If invoked with
|
|
<constant>SD_EVENT_ONESHOT</constant> the event source will be
|
|
enabled but automatically reset to
|
|
<constant>SD_EVENT_OFF</constant> after the event source was
|
|
dispatched once.</para>
|
|
|
|
<para>Event sources that are disabled will not result in event
|
|
loop wakeups and will not be dispatched, until they are enabled
|
|
again.</para>
|
|
|
|
<para><function>sd_event_source_get_enabled()</function> may be
|
|
used to query whether the event source object
|
|
<parameter>source</parameter> is currently enabled or not. It
|
|
returns the enablement state in
|
|
<parameter>enabled</parameter>.</para>
|
|
|
|
<para>Event source objects are enabled when they are first created
|
|
with calls such as
|
|
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
|
|
depending on the event source type they are enabled continuously
|
|
(<constant>SD_EVENT_ON</constant>) or only for a single invocation
|
|
of the event source handler
|
|
(<constant>SD_EVENT_ONESHOT</constant>). For details see the
|
|
respective manual pages.</para>
|
|
|
|
<para>As event source objects stay active and may be dispatched as
|
|
long as there is at least one reference to them, in many cases it
|
|
is a good idea to combine a call to
|
|
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
with a prior call to
|
|
<function>sd_event_source_set_enabled()</function> with
|
|
<constant>SD_EVENT_OFF</constant>, to ensure the event source is
|
|
not dispatched again until all other remaining references are dropped.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Return Value</title>
|
|
|
|
<para>On success, <function>sd_event_source_set_enabled()</function> and
|
|
<function>sd_event_source_get_enabled()</function> return a
|
|
non-negative integer. On failure, they return a negative
|
|
errno-style error code.</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Errors</title>
|
|
|
|
<para>Returned errors may indicate the following problems:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><constant>-EINVAL</constant></term>
|
|
|
|
<listitem><para><parameter>source</parameter> is not a valid
|
|
pointer to an <structname>sd_event_source</structname>
|
|
object.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-ENOMEM</constant></term>
|
|
|
|
<listitem><para>Not enough memory.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><constant>-ECHILD</constant></term>
|
|
|
|
<listitem><para>The event loop has been created in a different process.</para></listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<xi:include href="libsystemd-pkgconfig.xml" />
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<para>
|
|
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|