man/sd_event_set_watchdog.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_event_set_watchdog</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_event_set_watchdog</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_event_set_watchdog</refname>
  20     <refname>sd_event_get_watchdog</refname>
  21
  22     <refpurpose>Enable event loop watchdog support</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <funcsynopsis>
  27       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  28
  29       <funcprototype>
  30         <funcdef>int <function>sd_event_set_watchdog</function></funcdef>
  31         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  32         <paramdef>int b</paramdef>
  33       </funcprototype>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_event_get_watchdog</function></funcdef>
  37         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  38       </funcprototype>
  39
  40     </funcsynopsis>
  41   </refsynopsisdiv>
  42
  43   <refsect1>
  44     <title>Description</title>
  45
  46     <para><function>sd_event_set_watchdog()</function> may be used to
  47     enable or disable automatic watchdog notification support in the
  48     event loop object specified in the <parameter>event</parameter>
  49     parameter. Specifically, depending on the <parameter>b</parameter>
  50     boolean argument this will make sure the event loop wakes up in
  51     regular intervals and sends watchdog notification messages to the
  52     service manager, if this was requested by the service
  53     manager. Watchdog support is determined with
  54     <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  55     and watchdog messages are sent with
  56     <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. See
  57     the <varname>WatchdogSec=</varname> setting in
  58     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  59     for details on how to enable watchdog support for a service and
  60     the protocol used. The wake-up interval is chosen as half the
  61     watchdog timeout declared by the service manager via the
  62     <varname>$WATCHDOG_USEC</varname> environment variable. If the
  63     service manager did not request watchdog notifications, or if the
  64     process was not invoked by the service manager this call with a
  65     true <parameter>b</parameter> parameter executes no
  66     operation. Passing a false <parameter>b</parameter> parameter will
  67     disable the automatic sending of watchdog notification messages if
  68     it was enabled before. Newly allocated event loop objects have
  69     this feature disabled.</para>
  70
  71     <para>The first watchdog notification message is sent immediately
  72     when <function>sd_event_set_watchdog()</function> is invoked with
  73     a true <parameter>b</parameter> parameter.</para>
  74
  75     <para>The watchdog logic is designed to allow the service manager
  76     to automatically detect services that ceased processing of
  77     incoming events, and thus appear "hung". Watchdog notifications
  78     are sent out only at the beginning of each event loop
  79     iteration. If an event source dispatch function blocks for an
  80     excessively long time and does not return execution to the event
  81     loop quickly, this might hence cause the notification message to
  82     be delayed, and possibly result in abnormal program termination,
  83     as configured in the service unit file.</para>
  84
  85     <para><function>sd_event_get_watchdog()</function> may be used to
  86     determine whether watchdog support was previously requested by a
  87     call to <function>sd_event_set_watchdog()</function> with a true
  88     <parameter>b</parameter> parameter and successfully
  89     enabled.</para>
  90   </refsect1>
  91
  92   <refsect1>
  93     <title>Return Value</title>
  94
  95     <para>On success, <function>sd_event_set_watchdog()</function> and
  96     <function>sd_event_get_watchdog()</function> return a non-zero positive integer if the service manager
  97     requested watchdog support and watchdog support was successfully enabled. They return zero if the service
  98     manager did not request watchdog support, or if watchdog support was explicitly disabled with a false
  99     <parameter>b</parameter> parameter. On failure, they return a negative errno-style error code.</para>
 100
 101     <refsect2>
 102       <title>Errors</title>
 103
 104       <para>Returned errors may indicate the following problems:</para>
 105
 106       <variablelist>
 107
 108         <varlistentry>
 109           <term><constant>-ECHILD</constant></term>
 110
 111           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 112         </varlistentry>
 113
 114         <varlistentry>
 115           <term><constant>-EINVAL</constant></term>
 116
 117           <listitem><para>The passed event loop object was invalid.</para></listitem>
 118         </varlistentry>
 119
 120       </variablelist>
 121     </refsect2>
 122   </refsect1>
 123
 124   <xi:include href="libsystemd-pkgconfig.xml" />
 125
 126   <refsect1>
 127     <title>History</title>
 128     <para><function>sd_event_set_watchdog()</function> and
 129     <function>sd_event_get_watchdog()</function> were added in version 229.</para>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>See Also</title>
 134
 135     <para><simplelist type="inline">
 136       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 137       <member><citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 138       <member><citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 139       <member><citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 140       <member><citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 141       <member><citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 142       <member><citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 143       <member><citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 144       <member><citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 145       <member><citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 146       <member><citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 147       <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 148     </simplelist></para>
 149   </refsect1>
 150
 151 </refentry>