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 This file is part of elogind.
8 Copyright 2010 Lennart Poettering
10 elogind 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 elogind 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 elogind; 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>elogind</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 <elogind/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 by a service
101 to notify the service manager about state changes. It can be used
102 to send arbitrary information, encoded in an
103 environment-block-like string. Most importantly, it can be used for
104 start-up completion notification.</para>
106 <para>If the <parameter>unset_environment</parameter> parameter is
107 non-zero, <function>sd_notify()</function> will unset the
108 <varname>$NOTIFY_SOCKET</varname> environment variable before
109 returning (regardless of whether the function call itself
110 succeeded or not). Further calls to
111 <function>sd_notify()</function> will then fail, but the variable
112 is no longer inherited by child processes.</para>
114 <para>The <parameter>state</parameter> parameter should contain a
115 newline-separated list of variable assignments, similar in style
116 to an environment block. A trailing newline is implied if none is
117 specified. The string may contain any kind of variable
118 assignments, but the following shall be considered
125 <listitem><para>Tells the service manager that service startup
126 is finished. This is only used by elogind if the service
127 definition file has Type=notify set. Since there is little
128 value in signaling non-readiness, the only value services
129 should send is <literal>READY=1</literal> (i.e.
130 <literal>READY=0</literal> is not defined).</para></listitem>
134 <term>RELOADING=1</term>
136 <listitem><para>Tells the service manager that the service is
137 reloading its configuration. This is useful to allow the
138 service manager to track the service's internal state, and
139 present it to the user. Note that a service that sends this
140 notification must also send a <literal>READY=1</literal>
141 notification when it completed reloading its
142 configuration.</para></listitem>
146 <term>STOPPING=1</term>
148 <listitem><para>Tells the service manager that the service is
149 beginning its shutdown. This is useful to allow the service
150 manager to track the service's internal state, and present it
151 to the user.</para></listitem>
155 <term>STATUS=...</term>
157 <listitem><para>Passes a single-line UTF-8 status string back
158 to the service manager that describes the service state. This
159 is free-form and can be used for various purposes: general
160 state feedback, fsck-like programs could pass completion
161 percentages and failing programs could pass a human-readable
162 error message. Example: <literal>STATUS=Completed 66% of file
163 system check...</literal></para></listitem>
167 <term>ERRNO=...</term>
169 <listitem><para>If a service fails, the errno-style error
170 code, formatted as string. Example: <literal>ERRNO=2</literal>
171 for ENOENT.</para></listitem>
175 <term>BUSERROR=...</term>
177 <listitem><para>If a service fails, the D-Bus error-style
179 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
183 <term>MAINPID=...</term>
185 <listitem><para>The main process ID (PID) of the service, in
186 case the service manager did not fork off the process itself.
187 Example: <literal>MAINPID=4711</literal></para></listitem>
191 <term>WATCHDOG=1</term>
193 <listitem><para>Tells the service manager to update the
194 watchdog timestamp. This is the keep-alive ping that services
195 need to issue in regular intervals if
196 <varname>WatchdogSec=</varname> is enabled for it. See
197 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
198 for information how to enable this functionality and
199 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
200 for the details of how the service can check whether the
201 watchdog is enabled. </para></listitem>
206 <term>FDSTORE=1</term>
208 <listitem><para>Stores additional file descriptors in the
209 service manager. File descriptors sent this way will be
210 maintained per-service by the service manager and be passed
211 again using the usual file descriptor passing logic on the
212 next invocation of the service (see
213 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
214 This is useful for implementing service restart schemes where
215 services serialize their state to <filename>/run</filename>,
216 push their file descriptors to the system manager, and are
217 then restarted, retrieving their state again via socket
218 passing and <filename>/run</filename>. Note that the service
219 manager will accept messages for a service only if
220 <varname>FileDescriptorStoreMax=</varname> is set to non-zero
221 for it (defaults to zero). See
222 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
223 for details. Multiple arrays of file descriptors may be sent
224 in separate messages, in which case the arrays are combined.
225 Note that the service manager removes duplicate file
226 descriptors before passing them to the service. Use
227 <function>sd_pid_notify_with_fds()</function> to send messages
228 with <literal>FDSTORE=1</literal>, see
229 below.</para></listitem>
233 <term>FDNAME=...</term>
235 <listitem><para>When used in combination with
236 <varname>FDSTORE=1</varname>, specifies a name for the
237 submitted file descriptors. This name is passed to the service
238 during activation, and may be queried using
239 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
240 descriptors submitted without this field set, will implicitly
241 get the name <literal>stored</literal> assigned. Note that, if
242 multiple file descriptors are submitted at once, the specified
243 name will be assigned to all of them. In order to assign
244 different names to submitted file descriptors, submit them in
245 separate invocations of
246 <function>sd_pid_notify_with_fds()</function>. The name may
247 consist of any ASCII character, but must not contain control
248 characters or <literal>:</literal>. It may not be longer than
249 255 characters. If a submitted name does not follow these
250 restrictions, it is ignored.</para></listitem>
254 <term>WATCHDOG_USEC=...</term>
256 <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
257 Notice that this is not available when using <function>sd_event_set_watchdog()</function>
258 or <function>sd_watchdog_enabled()</function>.
259 Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
264 <para>It is recommended to prefix variable names that are not
265 listed above with <varname>X_</varname> to avoid namespace
268 <para>Note that elogind will accept status data sent from a
269 service only if the <varname>NotifyAccess=</varname> option is
270 correctly set in the service definition file. See
271 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
274 <para><function>sd_notifyf()</function> is similar to
275 <function>sd_notify()</function> but takes a
276 <function>printf()</function>-like format string plus
279 <para><function>sd_pid_notify()</function> and
280 <function>sd_pid_notifyf()</function> are similar to
281 <function>sd_notify()</function> and
282 <function>sd_notifyf()</function> but take a process ID (PID) to
283 use as originating PID for the message as first argument. This is
284 useful to send notification messages on behalf of other processes,
285 provided the appropriate privileges are available. If the PID
286 argument is specified as 0, the process ID of the calling process
287 is used, in which case the calls are fully equivalent to
288 <function>sd_notify()</function> and
289 <function>sd_notifyf()</function>.</para>
291 <para><function>sd_pid_notify_with_fds()</function> is similar to
292 <function>sd_pid_notify()</function> but takes an additional array
293 of file descriptors. These file descriptors are sent along the
294 notification message to the service manager. This is particularly
295 useful for sending <literal>FDSTORE=1</literal> messages, as
296 described above. The additional arguments are a pointer to the
297 file descriptor array plus the number of file descriptors in the
298 array. If the number of file descriptors is passed as 0, the call
299 is fully equivalent to <function>sd_pid_notify()</function>, i.e.
300 no file descriptors are passed. Note that sending file descriptors
301 to the service manager on messages that do not expect them (i.e.
302 without <literal>FDSTORE=1</literal>) they are immediately closed
307 <title>Return Value</title>
309 <para>On failure, these calls return a negative errno-style error
310 code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence
311 no status data could be sent, 0 is returned. If the status was
312 sent, these functions return with a positive return value. In
313 order to support both, init systems that implement this scheme and
314 those which do not, it is generally recommended to ignore the
315 return value of this call.</para>
321 <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
323 <para>These functions send a single datagram with the
324 state string as payload to the <constant>AF_UNIX</constant> socket
325 referenced in the <varname>$NOTIFY_SOCKET</varname> environment
326 variable. If the first character of
327 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
328 string is understood as Linux abstract namespace socket. The
329 datagram is accompanied by the process credentials of the sending
330 service, using SCM_CREDENTIALS.</para>
334 <title>Environment</title>
336 <variablelist class='environment-variables'>
338 <term><varname>$NOTIFY_SOCKET</varname></term>
340 <listitem><para>Set by the service manager for supervised
341 processes for status and start-up completion notification.
342 This environment variable specifies the socket
343 <function>sd_notify()</function> talks to. See above for
344 details.</para></listitem>
350 <title>Examples</title>
353 <title>Start-up Notification</title>
355 <para>When a service finished starting up, it might issue the
356 following call to notify the service manager:</para>
358 <programlisting>sd_notify(0, "READY=1");</programlisting>
362 <title>Extended Start-up Notification</title>
364 <para>A service could send the following after completing
365 initialization:</para>
367 <programlisting>sd_notifyf(0, "READY=1\n"
368 "STATUS=Processing requests...\n"
370 (unsigned long) getpid());</programlisting>
374 <title>Error Cause Notification</title>
376 <para>A service could send the following shortly before exiting, on failure:</para>
378 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
381 errno);</programlisting>
385 <title>Store a File Descriptor in the Service Manager</title>
387 <para>To store an open file descriptor in the service manager,
388 in order to continue operation after a service restart without
389 losing state, use <literal>FDSTORE=1</literal>:</para>
391 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
396 <title>See Also</title>
398 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
399 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
400 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
401 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
402 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
403 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
404 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>