1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_notify"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>sd_notify</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>sd_notify</refentrytitle>
43 <manvolnum>3</manvolnum>
47 <refname>sd_notify</refname>
48 <refname>sd_notifyf</refname>
49 <refname>sd_pid_notify</refname>
50 <refname>sd_pid_notifyf</refname>
51 <refname>sd_pid_notify_with_fds</refname>
52 <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
57 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
60 <funcdef>int <function>sd_notify</function></funcdef>
61 <paramdef>int <parameter>unset_environment</parameter></paramdef>
62 <paramdef>const char *<parameter>state</parameter></paramdef>
66 <funcdef>int <function>sd_notifyf</function></funcdef>
67 <paramdef>int <parameter>unset_environment</parameter></paramdef>
68 <paramdef>const char *<parameter>format</parameter></paramdef>
69 <paramdef>...</paramdef>
73 <funcdef>int <function>sd_pid_notify</function></funcdef>
74 <paramdef>pid_t <parameter>pid</parameter></paramdef>
75 <paramdef>int <parameter>unset_environment</parameter></paramdef>
76 <paramdef>const char *<parameter>state</parameter></paramdef>
80 <funcdef>int <function>sd_pid_notifyf</function></funcdef>
81 <paramdef>pid_t <parameter>pid</parameter></paramdef>
82 <paramdef>int <parameter>unset_environment</parameter></paramdef>
83 <paramdef>const char *<parameter>format</parameter></paramdef>
84 <paramdef>...</paramdef>
88 <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef>
89 <paramdef>pid_t <parameter>pid</parameter></paramdef>
90 <paramdef>int <parameter>unset_environment</parameter></paramdef>
91 <paramdef>const char *<parameter>state</parameter></paramdef>
92 <paramdef>const int *<parameter>fds</parameter></paramdef>
93 <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
99 <title>Description</title>
100 <para><function>sd_notify()</function> may be called
101 by a service to notify the service manager about
102 state changes. It can be used to send arbitrary
103 information, encoded in an environment-block-like
104 string. Most importantly it can be used for start-up
105 completion notification.</para>
107 <para>If the <parameter>unset_environment</parameter>
108 parameter is non-zero, <function>sd_notify()</function>
109 will unset the <varname>$NOTIFY_SOCKET</varname>
110 environment variable before returning (regardless of
111 whether the function call itself succeeded or
112 not). Further calls to
113 <function>sd_notify()</function> will then fail, but
114 the variable is no longer inherited by child
117 <para>The <parameter>state</parameter> parameter
118 should contain a newline-separated list of variable
119 assignments, similar in style to an environment
120 block. A trailing newline is implied if none is
121 specified. The string may contain any kind of variable
122 assignments, but the following shall be considered
129 <listitem><para>Tells the service
130 manager that service startup is
131 finished. This is only used by systemd
132 if the service definition file has
133 Type=notify set. Since there is little
134 value in signaling non-readiness, the
135 only value services should send is
136 <literal>READY=1</literal>
137 (i.e. <literal>READY=0</literal> is
138 not defined).</para></listitem>
142 <term>RELOADING=1</term>
144 <listitem><para>Tells the service manager
145 that the service is reloading its
146 configuration. This is useful to allow
147 the service manager to track the service's
148 internal state, and present it to the
149 user. Note that a service that sends
150 this notification must also send a
151 <literal>READY=1</literal>
152 notification when it completed
154 configuration.</para></listitem>
158 <term>STOPPING=1</term>
160 <listitem><para>Tells the service manager
161 that the service is beginning its
162 shutdown. This is useful to allow the
163 service manager to track the service's
164 internal state, and present it to the
165 user.</para></listitem>
169 <term>STATUS=...</term>
171 <listitem><para>Passes a single-line
172 UTF-8 status string back to the service manager
173 that describes the service state. This
174 is free-form and can be used for
175 various purposes: general state
176 feedback, fsck-like programs could
177 pass completion percentages and
178 failing programs could pass a human
179 readable error message. Example:
180 <literal>STATUS=Completed 66% of file
182 check...</literal></para></listitem>
186 <term>ERRNO=...</term>
188 <listitem><para>If a service fails, the
189 errno-style error code, formatted as
190 string. Example: <literal>ERRNO=2</literal> for
191 ENOENT.</para></listitem>
195 <term>BUSERROR=...</term>
197 <listitem><para>If a service fails, the
198 D-Bus error-style error code. Example:
199 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
203 <term>MAINPID=...</term>
205 <listitem><para>The main process ID (PID) of the
206 service, in case the service manager did
207 not fork off the process
209 <literal>MAINPID=4711</literal></para></listitem>
213 <term>WATCHDOG=1</term>
215 <listitem><para>Tells the service manager to
216 update the watchdog timestamp. This is
217 the keep-alive ping that services need
218 to issue in regular intervals if
219 <varname>WatchdogSec=</varname> is
221 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
222 for information how to enable this
224 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
225 for the details of how the service can
226 check if the the watchdog is enabled.
232 <term>FDSTORE=1</term>
234 <listitem><para>Stores additional file
235 descriptors in the service
236 manager. File descriptors sent this
237 way will be maintained per-service by
238 the service manager and be passed
239 again using the usual file descriptor
240 passing logic on the next invocation
242 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). This
243 is useful for implementing service
244 restart schemes where services
245 serialize their state to
246 <filename>/run</filename>, push their
247 file descriptors to the system
248 manager, and are then restarted,
249 retrieving their state again via
251 <filename>/run</filename>. Note that
252 the service manager will accept
253 messages for a service only if
254 <varname>FileDescriptorStoreMax=</varname>
255 is set to non-zero for it (defaults to
257 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
258 for details. Multiple arrays of file
259 descriptors may be sent in separate
260 messages, in which case the arrays are
261 combined. Note that the service
262 manager removes duplicate file
263 descriptors before passing them to the
265 <function>sd_pid_notify_with_fds()</function>
266 to send messages with
267 <literal>FDSTORE=1</literal>, see
268 below.</para></listitem>
273 <para>It is recommended to prefix variable names that
274 are not listed above with <varname>X_</varname> to
275 avoid namespace clashes.</para>
277 <para>Note that systemd will accept status data sent
278 from a service only if the
279 <varname>NotifyAccess=</varname> option is correctly
280 set in the service definition file. See
281 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
284 <para><function>sd_notifyf()</function> is similar to
285 <function>sd_notify()</function> but takes a
286 <function>printf()</function>-like format string plus
289 <para><function>sd_pid_notify()</function> and
290 <function>sd_pid_notifyf()</function> are similar to
291 <function>sd_notify()</function> and
292 <function>sd_notifyf()</function> but take a process
293 ID (PID) to use as originating PID for the message as
294 first argument. This is useful to send notification
295 messages on behalf of other processes, provided the
296 appropriate privileges are available. If the PID
297 argument is specified as 0 the process ID of the
298 calling process is used, in which case the calls are
299 fully equivalent to <function>sd_notify()</function>
300 and <function>sd_notifyf()</function>.</para>
302 <para><function>sd_pid_notify_with_fds()</function> is
303 similar to <function>sd_pid_notify()</function> but
304 takes an additional array of file descriptors. These
305 file descriptors are sent along the notification
306 message to the service manager. This is particularly
307 useful for sending <literal>FDSTORE=1</literal>
308 messages, as described above. The additional arguments
309 are a pointer to the file descriptor array plus the
310 number of file descriptors in the array. If the number
311 of file descriptors is passed as 0, the call is fully
312 equivalent to <function>sd_pid_notify()</function>,
313 i.e. no file descriptors are passed. Note that sending
314 file descriptors to the service manager on messages
315 that do not expect them (i.e. without
316 <literal>FDSTORE=1</literal>) they are immediately
317 closed on reception.</para>
321 <title>Return Value</title>
323 <para>On failure, these calls return a negative
324 errno-style error code. If
325 <varname>$NOTIFY_SOCKET</varname> was not set and
326 hence no status data could be sent, 0 is returned. If
327 the status was sent, these functions return with a
328 positive return value. In order to support both, init
329 systems that implement this scheme and those which
330 do not, it is generally recommended to ignore the return
331 value of this call.</para>
337 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
339 <para>Internally, these functions send a single
340 datagram with the state string as payload to the
341 <constant>AF_UNIX</constant> socket referenced in the
342 <varname>$NOTIFY_SOCKET</varname> environment
343 variable. If the first character of
344 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is
345 understood as Linux abstract namespace socket. The
346 datagram is accompanied by the process credentials of
347 the sending service, using SCM_CREDENTIALS.</para>
351 <title>Environment</title>
353 <variablelist class='environment-variables'>
355 <term><varname>$NOTIFY_SOCKET</varname></term>
357 <listitem><para>Set by the service manager
358 for supervised processes for status
359 and start-up completion
360 notification. This environment variable
362 <function>sd_notify()</function> talks
363 to. See above for details.</para></listitem>
369 <title>Examples</title>
372 <title>Start-up Notification</title>
374 <para>When a service finished starting up, it
375 might issue the following call to notify
376 the service manager:</para>
378 <programlisting>sd_notify(0, "READY=1");</programlisting>
382 <title>Extended Start-up Notification</title>
384 <para>A service could send the following after
385 completing initialization:</para>
387 <programlisting>sd_notifyf(0, "READY=1\n"
388 "STATUS=Processing requests...\n"
390 (unsigned long) getpid());</programlisting>
394 <title>Error Cause Notification</title>
396 <para>A service could send the following shortly before exiting, on failure:</para>
398 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
401 errno);</programlisting>
405 <title>Store a File Descriptor in the Service Manager</title>
407 <para>To store an open file descriptor in the
408 service manager, in order to continue
409 operation after a service restart without
411 <literal>FDSTORE=1</literal>:</para>
413 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting>
418 <title>See Also</title>
420 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
421 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
422 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
423 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
424 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>