Debian Codegraph @

upstream/debian-unstable/man3/sd_watchdog_enabled.3

raw
1 '\" t
2 .TH "SD_WATCHDOG_ENABLED" "3" "" "systemd 261~rc3" "sd_watchdog_enabled"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_watchdog_enabled \- Check whether the service manager expects watchdog keep\-alive notifications from a service
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-daemon\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_watchdog_enabled('u
32 .BI "int sd_watchdog_enabled(int\ " "unset_environment" ", uint64_t\ *" "usec" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_watchdog_enabled()\fR
36 may be called by a service to detect whether the service manager expects regular keep\-alive watchdog notification events from it, and the timeout after which the manager will act on the service if it did not get such a notification\&.
37 .PP
38 If the
39 \fI$WATCHDOG_USEC\fR
40 environment variable is set, and the
41 \fI$WATCHDOG_PID\fR
42 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
43 \fBsd_notify\fR(3)
44 with a message string of
45 "WATCHDOG=1"\&.
46 .PP
47 If the
48 \fIunset_environment\fR
49 parameter is non\-zero,
50 \fBsd_watchdog_enabled()\fR
51 will unset the
52 \fI$WATCHDOG_USEC\fR
53 and
54 \fI$WATCHDOG_PID\fR
55 environment variables before returning (regardless of whether the function call itself succeeded or not)\&. Those variables are no longer inherited by child processes\&. Further calls to
56 \fBsd_watchdog_enabled()\fR
57 will also return with zero\&.
58 .PP
59 If the
60 \fIusec\fR
61 parameter is non\-\fBNULL\fR,
62 \fBsd_watchdog_enabled()\fR
63 will write the timeout in μs for the watchdog logic to it\&.
64 .PP
65 To enable service supervision with the watchdog logic, use
66 \fIWatchdogSec=\fR
67 in service files\&. See
68 \fBsystemd.service\fR(5)
69 for details\&.
70 .PP
71 Use
72 \fBsd_event_set_watchdog\fR(3)
73 to enable automatic watchdog support in
74 \fBsd-event\fR(3)\-based event loops\&.
75 .SH "RETURN VALUE"
76 .PP
77 On failure, this call returns a negative 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
78 \fIusec\fR
79 parameter is valid after the call\&.
80 .SH "NOTES"
81 .PP
82 Functions described here are available as a shared library, which can be compiled against and linked to with the
83 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
84 file\&.
85 .PP
86 The code described here uses
87 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
88 \fBsetenv\fR(3)
89 from a parallel thread\&. It is recommended to only do calls to
90 \fBsetenv()\fR
91 from an early phase of the program when no other threads have been started\&.
92 .PP
93 Internally, this function parses the
94 \fI$WATCHDOG_PID\fR
95 and
96 \fI$WATCHDOG_USEC\fR
97 environment variable\&. The call will ignore these variables if
98 \fI$WATCHDOG_PID\fR
99 does not contain the PID of the current process, under the assumption that in that case, the variables were set for a different process further up the process tree\&.
100 .SH "ENVIRONMENT"
101 .PP
102 \fI$WATCHDOG_PID\fR
103 .RS 4
104 Set by the system manager for supervised process for which watchdog support is enabled, and contains the PID of that process\&. See above for details\&.
105 .sp
106 Added in version 209\&.
107 .RE
108 .PP
109 \fI$WATCHDOG_USEC\fR
110 .RS 4
111 Set by the system manager for supervised process for which watchdog support is enabled, and contains the watchdog timeout in μs\&. See above for details\&.
112 .sp
113 Added in version 209\&.
114 .RE
115 .SH "HISTORY"
116 .PP
117 \fBsd_watchdog_enabled()\fR
118 was added in version 209\&.
119 .SH "SEE ALSO"
120 .PP
121 \fBsystemd\fR(1), \fBsd-daemon\fR(3), \fBdaemon\fR(7), \fBsystemd.service\fR(5), \fBsd_notify\fR(3), \fBsd_event_set_watchdog\fR(3)