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 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 systemd 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 if the 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>
234 <para>It is recommended to prefix variable names that are not
235 listed above with <varname>X_</varname> to avoid namespace
238 <para>Note that systemd will accept status data sent from a
239 service only if the <varname>NotifyAccess=</varname> option is
240 correctly set in the service definition file. See
241 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
244 <para><function>sd_notifyf()</function> is similar to
245 <function>sd_notify()</function> but takes a
246 <function>printf()</function>-like format string plus
249 <para><function>sd_pid_notify()</function> and
250 <function>sd_pid_notifyf()</function> are similar to
251 <function>sd_notify()</function> and
252 <function>sd_notifyf()</function> but take a process ID (PID) to
253 use as originating PID for the message as first argument. This is
254 useful to send notification messages on behalf of other processes,
255 provided the appropriate privileges are available. If the PID
256 argument is specified as 0 the process ID of the calling process
257 is used, in which case the calls are fully equivalent to
258 <function>sd_notify()</function> and
259 <function>sd_notifyf()</function>.</para>
261 <para><function>sd_pid_notify_with_fds()</function> is similar to
262 <function>sd_pid_notify()</function> but takes an additional array
263 of file descriptors. These file descriptors are sent along the
264 notification message to the service manager. This is particularly
265 useful for sending <literal>FDSTORE=1</literal> messages, as
266 described above. The additional arguments are a pointer to the
267 file descriptor array plus the number of file descriptors in the
268 array. If the number of file descriptors is passed as 0, the call
269 is fully equivalent to <function>sd_pid_notify()</function>, i.e.
270 no file descriptors are passed. Note that sending file descriptors
271 to the service manager on messages that do not expect them (i.e.
272 without <literal>FDSTORE=1</literal>) they are immediately closed
277 <title>Return Value</title>
279 <para>On failure, these calls return a negative errno-style error
280 code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence
281 no status data could be sent, 0 is returned. If the status was
282 sent, these functions return with a positive return value. In
283 order to support both, init systems that implement this scheme and
284 those which do not, it is generally recommended to ignore the
285 return value of this call.</para>
291 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
293 <para>Internally, these functions send a single datagram with the
294 state string as payload to the <constant>AF_UNIX</constant> socket
295 referenced in the <varname>$NOTIFY_SOCKET</varname> environment
296 variable. If the first character of
297 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
298 string is understood as Linux abstract namespace socket. The
299 datagram is accompanied by the process credentials of the sending
300 service, using SCM_CREDENTIALS.</para>
304 <title>Environment</title>
306 <variablelist class='environment-variables'>
308 <term><varname>$NOTIFY_SOCKET</varname></term>
310 <listitem><para>Set by the service manager for supervised
311 processes for status and start-up completion notification.
312 This environment variable specifies the socket
313 <function>sd_notify()</function> talks to. See above for
314 details.</para></listitem>
320 <title>Examples</title>
323 <title>Start-up Notification</title>
325 <para>When a service finished starting up, it might issue the
326 following call to notify the service manager:</para>
328 <programlisting>sd_notify(0, "READY=1");</programlisting>
332 <title>Extended Start-up Notification</title>
334 <para>A service could send the following after completing
335 initialization:</para>
337 <programlisting>sd_notifyf(0, "READY=1\n"
338 "STATUS=Processing requests...\n"
340 (unsigned long) getpid());</programlisting>
344 <title>Error Cause Notification</title>
346 <para>A service could send the following shortly before exiting, on failure:</para>
348 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
351 errno);</programlisting>
355 <title>Store a File Descriptor in the Service Manager</title>
357 <para>To store an open file descriptor in the service manager,
358 in order to continue operation after a service restart without
359 losing state use <literal>FDSTORE=1</literal>:</para>
361 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting>
366 <title>See Also</title>
368 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
369 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
370 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
371 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
372 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>