along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sd_watchdog_enabled">
+<refentry id="sd_watchdog_enabled"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_watchdog_enabled</title>
<funcprototype>
<funcdef>int <function>sd_watchdog_enabled</function></funcdef>
<paramdef>int <parameter>unset_environment</parameter></paramdef>
- <paramdef>
const uint64_t *<parameter>usec</parameter></paramdef>
+ <paramdef>uint64_t *<parameter>usec</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
which the manager will act on the service if it did
not get such a notification.</para>
+ <para>If the <varname>$WATCHDOG_USEC</varname>
+ environment variable is set, and the
+ <varname>$WATCHDOG_PID</varname> variable is unset or
+ set to the PID of the current process, the service
+ manager expects notifications from this process. The
+ manager will usually terminate a service when it does
+ not get a notification message within the specified
+ time after startup and after each previous message. It
+ is recommended that a daemon sends a keep-alive
+ notification message to the service manager every half
+ of the time returned here. Notification messages may
+ be sent with
+ <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ with a message string of
+ <literal>WATCHDOG=1</literal>.</para>
+
<para>If the <parameter>unset_environment</parameter>
parameter is non-zero,
<function>sd_watchdog_enabled()</function> will unset
the <varname>$WATCHDOG_USEC</varname> and
<varname>$WATCHDOG_PID</varname> environment variables
- before returning (regardless of whether the function call
- itself succeeded or not). Further calls to
- <function>sd_watchdog_enabled()</function> will then
- return with zero, but the variable is no longer
- inherited by child processes.</para>
+ before returning (regardless of whether the function
+ call itself succeeded or not). Those variables are no
+ longer inherited by child processes. Further calls to
+ <function>sd_watchdog_enabled()</function> will also
+ return with zero.</para>
<para>If the <parameter>usec</parameter> parameter is
- non-NULL <function>sd_watchdog_enabled()</function>
- will return the timeout in µs for the watchdog
- logic. The service manager will usually terminate a
- service when it did not get a notification message
- within the specified time after startup and after each
- previous message. It is recommended that a daemon
- sends a keep-alive notification message to the service
- manager every half of the time returned
- here. Notification messages may be sent with
- <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- with a message string of
- <literal>WATCHDOG=1</literal>.</para>
+ non-NULL, <function>sd_watchdog_enabled()</function>
+ will write the timeout in µs for the watchdog
+ logic to it.</para>
<para>To enable service supervision with the watchdog
- logic use <varname>WatchdogSec=</varname> in service
+ logic, use <varname>WatchdogSec=</varname> in service
files. See
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
errno-style error code. If the service manager expects
watchdog keep-alive notification messages to be sent,
> 0 is returned, otherwise 0 is returned. Only if
- the return value is > 0 the
+ the return value is > 0, the
<parameter>usec</parameter> parameter is valid after
the call.</para>
</refsect1>
<refsect1>
<title>Notes</title>
- <para>This function is provided by the reference
- implementation of APIs for new-style daemons and
- distributed with the systemd package. The algorithm
- it implements is simple, and can easily be
- reimplemented in daemons if it is important to support
- this interface without using the reference
- implementation.</para>
+ <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
<para>Internally, this functions parses the
<varname>$WATCHDOG_PID</varname> and
<varname>$WATCHDOG_USEC</varname> environment
variable. The call will ignore these variables if
- <varname>$WATCHDOG_PID</varname> does containe the PID
+ <varname>$WATCHDOG_PID</varname> does not contain the PID
of the current process, under the assumption that in
- that case the variables were set for a different
+ that case, the variables were set for a different
process further up the process tree.</para>
-
- <para>For details about the algorithm check the
- liberally licensed reference implementation sources:
- <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
- and <ulink
- url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
-
- <para><function>sd_watchdog_enabled()</function> is
- implemented in the reference implementation's
- <filename>sd-daemon.c</filename> and
- <filename>sd-daemon.h</filename> files. These
- interfaces are available as a shared library, which can
- be compiled and linked to with the
- <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- file. Alternatively, applications consuming these APIs
- may copy the implementation into their source
- tree. For more details about the reference
- implementation see
- <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
-
- <para>If the reference implementation is used as
- drop-in files and -DDISABLE_SYSTEMD is set during
- compilation, these functions will always return 0 and
- otherwise become a NOP.</para>
</refsect1>
<refsect1>
</variablelist>
</refsect1>
+ <refsect1>
+ <title>History</title>
+
+ <para>The watchdog functionality and the
+ <varname>$WATCHDOG_USEC</varname> variable were
+ added in systemd-41.</para>
+
+ <para><function>sd_watchdog_enabled()</function>
+ function was added in systemd-209. Since that version
+ the <varname>$WATCHDOG_PID</varname> variable is also
+ set.</para>
+ </refsect1>
+
<refsect1>
<title>See Also</title>
<para>
~ianmdlvl / elogind.git / blobdiff