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