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.2/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.</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>See Also</title>
128
129    <para>
130      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
131      <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
132      <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
133      <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
134      <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
135      <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
136      <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
137      <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
138      <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
139      <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
140      <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
141      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
142    </para>
143  </refsect1>
144
145</refentry>
146