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">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id="sd_notify"
10 xmlns:xi="http://www.w3.org/2001/XInclude">
13 <title>sd_notify</title>
14 <productname>elogind</productname>
18 <contrib>Developer</contrib>
19 <firstname>Lennart</firstname>
20 <surname>Poettering</surname>
21 <email>lennart@poettering.net</email>
27 <refentrytitle>sd_notify</refentrytitle>
28 <manvolnum>3</manvolnum>
32 <refname>sd_notify</refname>
33 <refname>sd_notifyf</refname>
34 <refname>sd_pid_notify</refname>
35 <refname>sd_pid_notifyf</refname>
36 <refname>sd_pid_notify_with_fds</refname>
37 <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
42 <funcsynopsisinfo>#include <elogind/sd-daemon.h></funcsynopsisinfo>
45 <funcdef>int <function>sd_notify</function></funcdef>
46 <paramdef>int <parameter>unset_environment</parameter></paramdef>
47 <paramdef>const char *<parameter>state</parameter></paramdef>
51 <funcdef>int <function>sd_notifyf</function></funcdef>
52 <paramdef>int <parameter>unset_environment</parameter></paramdef>
53 <paramdef>const char *<parameter>format</parameter></paramdef>
54 <paramdef>…</paramdef>
58 <funcdef>int <function>sd_pid_notify</function></funcdef>
59 <paramdef>pid_t <parameter>pid</parameter></paramdef>
60 <paramdef>int <parameter>unset_environment</parameter></paramdef>
61 <paramdef>const char *<parameter>state</parameter></paramdef>
65 <funcdef>int <function>sd_pid_notifyf</function></funcdef>
66 <paramdef>pid_t <parameter>pid</parameter></paramdef>
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_with_fds</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>
77 <paramdef>const int *<parameter>fds</parameter></paramdef>
78 <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
84 <title>Description</title>
85 <para><function>sd_notify()</function> may be called by a service
86 to notify the service manager about state changes. It can be used
87 to send arbitrary information, encoded in an
88 environment-block-like string. Most importantly, it can be used for
89 start-up completion notification.</para>
91 <para>If the <parameter>unset_environment</parameter> parameter is
92 non-zero, <function>sd_notify()</function> will unset the
93 <varname>$NOTIFY_SOCKET</varname> environment variable before
94 returning (regardless of whether the function call itself
95 succeeded or not). Further calls to
96 <function>sd_notify()</function> will then fail, but the variable
97 is no longer inherited by child processes.</para>
99 <para>The <parameter>state</parameter> parameter should contain a
100 newline-separated list of variable assignments, similar in style
101 to an environment block. A trailing newline is implied if none is
102 specified. The string may contain any kind of variable
103 assignments, but the following shall be considered
110 <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its
111 configuration. This is only used by elogind if the service definition file has <varname>Type=notify</varname>
112 set. Since there is little value in signaling non-readiness, the only value services should send is
113 <literal>READY=1</literal> (i.e. <literal>READY=0</literal> is not defined).</para></listitem>
117 <term>RELOADING=1</term>
119 <listitem><para>Tells the service manager that the service is
120 reloading its configuration. This is useful to allow the
121 service manager to track the service's internal state, and
122 present it to the user. Note that a service that sends this
123 notification must also send a <literal>READY=1</literal>
124 notification when it completed reloading its
125 configuration. Reloads are propagated in the same way as they
126 are when initiated by the user.</para></listitem>
130 <term>STOPPING=1</term>
132 <listitem><para>Tells the service manager that the service is
133 beginning its shutdown. This is useful to allow the service
134 manager to track the service's internal state, and present it
135 to the user.</para></listitem>
139 <term>STATUS=…</term>
141 <listitem><para>Passes a single-line UTF-8 status string back
142 to the service manager that describes the service state. This
143 is free-form and can be used for various purposes: general
144 state feedback, fsck-like programs could pass completion
145 percentages and failing programs could pass a human-readable
146 error message. Example: <literal>STATUS=Completed 66% of file
147 system check…</literal></para></listitem>
153 <listitem><para>If a service fails, the errno-style error
154 code, formatted as string. Example: <literal>ERRNO=2</literal>
155 for ENOENT.</para></listitem>
159 <term>BUSERROR=…</term>
161 <listitem><para>If a service fails, the D-Bus error-style
163 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
167 <term>MAINPID=…</term>
169 <listitem><para>The main process ID (PID) of the service, in
170 case the service manager did not fork off the process itself.
171 Example: <literal>MAINPID=4711</literal></para></listitem>
175 <term>WATCHDOG=1</term>
177 <listitem><para>Tells the service manager to update the
178 watchdog timestamp. This is the keep-alive ping that services
179 need to issue in regular intervals if
180 <varname>WatchdogSec=</varname> is enabled for it. See
181 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
182 for information how to enable this functionality and
183 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
184 for the details of how the service can check whether the
185 watchdog is enabled. </para></listitem>
189 <term>WATCHDOG_USEC=…</term>
191 <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
192 Notice that this is not available when using <function>sd_event_set_watchdog()</function>
193 or <function>sd_watchdog_enabled()</function>.
194 Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
198 <term>EXTEND_TIMEOUT_USEC=…</term>
200 <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
201 corresponding the current state. The value specified is a time in microseconds during which the service must
202 send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
203 current state is beyond the original maximium times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>,
204 and <varname>TimeoutStopSec=</varname>.
205 See <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
206 for effects on the service timeouts.</para></listitem>
210 <term>FDSTORE=1</term>
212 <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will
213 be maintained per-service by the service manager and will later be handed back using the usual file descriptor
214 passing logic at the next invocation of the service, see
215 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is
216 useful for implementing services that can restart after an explicit request or a crash without losing
217 state. Any open sockets and other file descriptors which should not be closed during the restart may be stored
218 this way. Application state can either be serialized to a file in <filename>/run</filename>, or better, stored
219 in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory
220 file descriptor. Note that the service manager will accept messages for a service only if its
221 <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
222 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If file
223 descriptors sent are pollable (see
224 <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any
225 <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their
226 automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in
227 which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same
228 object) file descriptors before passing them to the service. Use <function>sd_pid_notify_with_fds()</function>
229 to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem>
233 <term>FDSTOREREMOVE=1</term>
235 <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with
236 <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem>
240 <term>FDNAME=…</term>
242 <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted
243 file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file
244 descriptors to remove. This name is passed to the service during activation, and may be queried using
245 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
246 descriptors submitted without this field set, will implicitly get the name <literal>stored</literal>
247 assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to
248 all of them. In order to assign different names to submitted file descriptors, submit them in separate
249 invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII
250 characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a
251 submitted name does not follow these restrictions, it is ignored.</para></listitem>
256 <para>It is recommended to prefix variable names that are not
257 listed above with <varname>X_</varname> to avoid namespace
260 <para>Note that elogind will accept status data sent from a
261 service only if the <varname>NotifyAccess=</varname> option is
262 correctly set in the service definition file. See
263 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
266 <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
267 the sending process is still around at the time PID 1 processes the message, or if the sending process is
268 explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
269 off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
270 <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
271 <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
272 attribute the message to the unit, and thus will ignore it, even if
273 <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
275 <para><function>sd_notifyf()</function> is similar to
276 <function>sd_notify()</function> but takes a
277 <function>printf()</function>-like format string plus
280 <para><function>sd_pid_notify()</function> and
281 <function>sd_pid_notifyf()</function> are similar to
282 <function>sd_notify()</function> and
283 <function>sd_notifyf()</function> but take a process ID (PID) to
284 use as originating PID for the message as first argument. This is
285 useful to send notification messages on behalf of other processes,
286 provided the appropriate privileges are available. If the PID
287 argument is specified as 0, the process ID of the calling process
288 is used, in which case the calls are fully equivalent to
289 <function>sd_notify()</function> and
290 <function>sd_notifyf()</function>.</para>
292 <para><function>sd_pid_notify_with_fds()</function> is similar to
293 <function>sd_pid_notify()</function> but takes an additional array
294 of file descriptors. These file descriptors are sent along the
295 notification message to the service manager. This is particularly
296 useful for sending <literal>FDSTORE=1</literal> messages, as
297 described above. The additional arguments are a pointer to the
298 file descriptor array plus the number of file descriptors in the
299 array. If the number of file descriptors is passed as 0, the call
300 is fully equivalent to <function>sd_pid_notify()</function>, i.e.
301 no file descriptors are passed. Note that sending file descriptors
302 to the service manager on messages that do not expect them (i.e.
303 without <literal>FDSTORE=1</literal>) they are immediately closed
308 <title>Return Value</title>
310 <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was
311 not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
312 positive value. In order to support both service managers that implement this scheme and those which do not, it is
313 generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
314 the notification message was enqueued properly, it does not reflect whether the message could be processed
315 successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
316 <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
323 <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
325 <para>These functions send a single datagram with the
326 state string as payload to the <constant>AF_UNIX</constant> socket
327 referenced in the <varname>$NOTIFY_SOCKET</varname> environment
328 variable. If the first character of
329 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
330 string is understood as Linux abstract namespace socket. The
331 datagram is accompanied by the process credentials of the sending
332 service, using SCM_CREDENTIALS.</para>
336 <title>Environment</title>
338 <variablelist class='environment-variables'>
340 <term><varname>$NOTIFY_SOCKET</varname></term>
342 <listitem><para>Set by the service manager for supervised
343 processes for status and start-up completion notification.
344 This environment variable specifies the socket
345 <function>sd_notify()</function> talks to. See above for
346 details.</para></listitem>
352 <title>Examples</title>
355 <title>Start-up Notification</title>
357 <para>When a service finished starting up, it might issue the
358 following call to notify the service manager:</para>
360 <programlisting>sd_notify(0, "READY=1");</programlisting>
364 <title>Extended Start-up Notification</title>
366 <para>A service could send the following after completing
367 initialization:</para>
369 <programlisting>sd_notifyf(0, "READY=1\n"
370 "STATUS=Processing requests…\n"
372 (unsigned long) getpid());</programlisting>
376 <title>Error Cause Notification</title>
378 <para>A service could send the following shortly before exiting, on failure:</para>
380 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
383 errno);</programlisting>
387 <title>Store a File Descriptor in the Service Manager</title>
389 <para>To store an open file descriptor in the service manager,
390 in order to continue operation after a service restart without
391 losing state, use <literal>FDSTORE=1</literal>:</para>
393 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
398 <title>See Also</title>
400 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
401 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
402 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
403 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
404 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
405 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
406 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>