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 service manager. File
209 descriptors sent this way will be maintained per-service by the service manager
210 and will be passed again using the usual file descriptor passing logic on the next
211 invocation of the service, see
212 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
213 This is useful for implementing service restart schemes where services serialize
214 their state to <filename>/run</filename>, push their file descriptors to the
215 system manager, and are then restarted, retrieving their state again via socket
216 passing and <filename>/run</filename>. Note that the service manager will accept
217 messages for a service only if <varname>FileDescriptorStoreMax=</varname> is set
218 to non-zero for it (defaults to zero, see
219 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
220 File descriptors must be pollable, see
221 <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
222 Multiple arrays of file descriptors may be sent in separate messages, in which
223 case the arrays are combined. Note that the service manager removes duplicate
224 file descriptors before passing them to the service. Use
225 <function>sd_pid_notify_with_fds()</function> to send messages with
226 <literal>FDSTORE=1</literal>, see below.</para></listitem>
230 <term>FDNAME=...</term>
232 <listitem><para>When used in combination with
233 <varname>FDSTORE=1</varname>, specifies a name for the
234 submitted file descriptors. This name is passed to the service
235 during activation, and may be queried using
236 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
237 descriptors submitted without this field set, will implicitly
238 get the name <literal>stored</literal> assigned. Note that, if
239 multiple file descriptors are submitted at once, the specified
240 name will be assigned to all of them. In order to assign
241 different names to submitted file descriptors, submit them in
242 separate invocations of
243 <function>sd_pid_notify_with_fds()</function>. The name may
244 consist of any ASCII character, but must not contain control
245 characters or <literal>:</literal>. It may not be longer than
246 255 characters. If a submitted name does not follow these
247 restrictions, it is ignored.</para></listitem>
251 <term>WATCHDOG_USEC=...</term>
253 <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
254 Notice that this is not available when using <function>sd_event_set_watchdog()</function>
255 or <function>sd_watchdog_enabled()</function>.
256 Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
261 <para>It is recommended to prefix variable names that are not
262 listed above with <varname>X_</varname> to avoid namespace
265 <para>Note that elogind will accept status data sent from a
266 service only if the <varname>NotifyAccess=</varname> option is
267 correctly set in the service definition file. See
268 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
271 <para><function>sd_notifyf()</function> is similar to
272 <function>sd_notify()</function> but takes a
273 <function>printf()</function>-like format string plus
276 <para><function>sd_pid_notify()</function> and
277 <function>sd_pid_notifyf()</function> are similar to
278 <function>sd_notify()</function> and
279 <function>sd_notifyf()</function> but take a process ID (PID) to
280 use as originating PID for the message as first argument. This is
281 useful to send notification messages on behalf of other processes,
282 provided the appropriate privileges are available. If the PID
283 argument is specified as 0, the process ID of the calling process
284 is used, in which case the calls are fully equivalent to
285 <function>sd_notify()</function> and
286 <function>sd_notifyf()</function>.</para>
288 <para><function>sd_pid_notify_with_fds()</function> is similar to
289 <function>sd_pid_notify()</function> but takes an additional array
290 of file descriptors. These file descriptors are sent along the
291 notification message to the service manager. This is particularly
292 useful for sending <literal>FDSTORE=1</literal> messages, as
293 described above. The additional arguments are a pointer to the
294 file descriptor array plus the number of file descriptors in the
295 array. If the number of file descriptors is passed as 0, the call
296 is fully equivalent to <function>sd_pid_notify()</function>, i.e.
297 no file descriptors are passed. Note that sending file descriptors
298 to the service manager on messages that do not expect them (i.e.
299 without <literal>FDSTORE=1</literal>) they are immediately closed
304 <title>Return Value</title>
306 <para>On failure, these calls return a negative errno-style error
307 code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence
308 no status data could be sent, 0 is returned. If the status was
309 sent, these functions return with a positive return value. In
310 order to support both, init systems that implement this scheme and
311 those which do not, it is generally recommended to ignore the
312 return value of this call.</para>
318 <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
320 <para>These functions send a single datagram with the
321 state string as payload to the <constant>AF_UNIX</constant> socket
322 referenced in the <varname>$NOTIFY_SOCKET</varname> environment
323 variable. If the first character of
324 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the
325 string is understood as Linux abstract namespace socket. The
326 datagram is accompanied by the process credentials of the sending
327 service, using SCM_CREDENTIALS.</para>
331 <title>Environment</title>
333 <variablelist class='environment-variables'>
335 <term><varname>$NOTIFY_SOCKET</varname></term>
337 <listitem><para>Set by the service manager for supervised
338 processes for status and start-up completion notification.
339 This environment variable specifies the socket
340 <function>sd_notify()</function> talks to. See above for
341 details.</para></listitem>
347 <title>Examples</title>
350 <title>Start-up Notification</title>
352 <para>When a service finished starting up, it might issue the
353 following call to notify the service manager:</para>
355 <programlisting>sd_notify(0, "READY=1");</programlisting>
359 <title>Extended Start-up Notification</title>
361 <para>A service could send the following after completing
362 initialization:</para>
364 <programlisting>sd_notifyf(0, "READY=1\n"
365 "STATUS=Processing requests...\n"
367 (unsigned long) getpid());</programlisting>
371 <title>Error Cause Notification</title>
373 <para>A service could send the following shortly before exiting, on failure:</para>
375 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
378 errno);</programlisting>
382 <title>Store a File Descriptor in the Service Manager</title>
384 <para>To store an open file descriptor in the service manager,
385 in order to continue operation after a service restart without
386 losing state, use <literal>FDSTORE=1</literal>:</para>
388 <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
393 <title>See Also</title>
395 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
396 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
397 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
398 <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
399 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
400 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
401 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>