mirror of
https://github.com/Dasharo/systemd.git
synced 2026-03-06 15:02:31 -08:00
71193c0b62
This is a natural use case, and instead of defining a wrapper to do this for us, let's just make this part of the API. Calling with NULL was not allowed, so this is not a breaking change to the interface. (After sd_event_source_is_enabled was originally added, we introduced sd_event_source_disable_unref() and other similar functions which accept NULL. So not accepting NULL here is likely to confuse people. Let's just make the API usable with minimal fuss.)
158 lines
6.6 KiB
XML
158 lines
6.6 KiB
XML
<?xml version='1.0'?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<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>
|
|
</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. If both the
|
|
<parameter>source</parameter> and the output parameter <parameter>enabled</parameter> are
|
|
<constant>NULL</constant>, this function returns false. Otherwise, <parameter>source</parameter> must be
|
|
a valid pointer to an <structname>sd_event_source</structname> object. If the output parameter
|
|
<parameter>enabled</parameter> is not <constant>NULL</constant>, it is set to the enablement state (one
|
|
of <constant>SD_EVENT_ON</constant>, <constant>SD_EVENT_OFF</constant>,
|
|
<constant>SD_EVENT_ONESHOT</constant>). The function also returns true if the event source is not
|
|
disabled.</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> returns a non-negative
|
|
integer. <function>sd_event_source_get_enabled()</function> returns zero if the source is disabled
|
|
(<constant>SD_EVENT_OFF</constant>) and a positive integer otherwise. On failure, they return a negative
|
|
errno-style error code.</para>
|
|
|
|
<refsect2>
|
|
<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>
|
|
</refsect2>
|
|
</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_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
<citerefentry><refentrytitle>sd_event_add_inotify</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>,
|
|
<citerefentry><refentrytitle>sd_event_source_set_ratelimit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|