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 <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
54 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
57 <funcdef>int <function>sd_notify</function></funcdef>
58 <paramdef>int <parameter>unset_environment</parameter></paramdef>
59 <paramdef>const char *<parameter>state</parameter></paramdef>
63 <funcdef>int <function>sd_notifyf</function></funcdef>
64 <paramdef>int <parameter>unset_environment</parameter></paramdef>
65 <paramdef>const char *<parameter>format</parameter></paramdef>
66 <paramdef>...</paramdef>
72 <title>Description</title>
73 <para><function>sd_notify()</function> may be called
74 by a service to notify the service manager about
75 state changes. It can be used to send arbitrary
76 information, encoded in an environment-block-like
77 string. Most importantly it can be used for start-up
78 completion notification.</para>
80 <para>If the <parameter>unset_environment</parameter>
81 parameter is non-zero, <function>sd_notify()</function>
82 will unset the <varname>$NOTIFY_SOCKET</varname>
83 environment variable before returning (regardless of
84 whether the function call itself succeeded or
85 not). Further calls to
86 <function>sd_notify()</function> will then fail, but
87 the variable is no longer inherited by child
90 <para>The <parameter>state</parameter> parameter
91 should contain a newline-separated list of variable
92 assignments, similar in style to an environment
93 block. A trailing newline is implied if none is
94 specified. The string may contain any kind of variable
95 assignments, but the following shall be considered
102 <listitem><para>Tells the service
103 manager that service startup is
104 finished. This is only used by systemd
105 if the service definition file has
106 Type=notify set. Since there is little
107 value in signaling non-readiness, the
108 only value services should send is
109 <literal>READY=1</literal>
110 (i.e. <literal>READY=0</literal> is
111 not defined).</para></listitem>
115 <term>RELOADING=1</term>
117 <listitem><para>Tells the service manager
118 that the service is reloading its
119 configuration. This is useful to allow
120 the service manager to track the service's
121 internal state, and present it to the
122 user. Note that a service that sends
123 this notification must also send a
124 <literal>READY=1</literal>
125 notification when it completed
127 configuration.</para></listitem>
131 <term>STOPPING=1</term>
133 <listitem><para>Tells the service manager
134 that the service is beginning its
135 shutdown. This is useful to allow the
136 service manager to track the service's
137 internal state, and present it to the
138 user.</para></listitem>
142 <term>STATUS=...</term>
144 <listitem><para>Passes a single-line
145 UTF-8 status string back to the service manager
146 that describes the service state. This
147 is free-form and can be used for
148 various purposes: general state
149 feedback, fsck-like programs could
150 pass completion percentages and
151 failing programs could pass a human
152 readable error message. Example:
153 <literal>STATUS=Completed 66% of file
155 check...</literal></para></listitem>
159 <term>ERRNO=...</term>
161 <listitem><para>If a service fails, the
162 errno-style error code, formatted as
163 string. Example: <literal>ERRNO=2</literal> for
164 ENOENT.</para></listitem>
168 <term>BUSERROR=...</term>
170 <listitem><para>If a service fails, the
171 D-Bus error-style error code. Example:
172 <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
176 <term>MAINPID=...</term>
178 <listitem><para>The main pid of the
179 service, in case the service manager did
180 not fork off the process
182 <literal>MAINPID=4711</literal></para></listitem>
186 <term>WATCHDOG=1</term>
188 <listitem><para>Tells systemd to
189 update the watchdog timestamp. This is
190 the keep-alive ping that services need
191 to issue in regular intervals if
192 <varname>WatchdogSec=</varname> is
194 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
195 for details. It is recommended to send
197 <varname>$WATCHDOG_PID</varname>
198 environment variable has been set to
199 the PID of the service process, in
200 every half the time interval that is
202 <varname>$WATCHDOG_USEC</varname>
203 environment variable. See
204 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
205 for details.</para></listitem>
209 <para>It is recommended to prefix variable names that
210 are not shown in the list above with
211 <varname>X_</varname> to avoid namespace
214 <para>Note that systemd will accept status data sent
215 from a service only if the
216 <varname>NotifyAccess=</varname> option is correctly
217 set in the service definition file. See
218 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
221 <para><function>sd_notifyf()</function> is similar to
222 <function>sd_notify()</function> but takes a
223 <function>printf()</function>-like format string plus
228 <title>Return Value</title>
230 <para>On failure, these calls return a negative
231 errno-style error code. If
232 <varname>$NOTIFY_SOCKET</varname> was not set and
233 hence no status data could be sent, 0 is returned. If
234 the status was sent, these functions return with a
235 positive return value. In order to support both, init
236 systems that implement this scheme and those which
237 do not, it is generally recommended to ignore the return
238 value of this call.</para>
244 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
246 <para>Internally, these functions send a single
247 datagram with the state string as payload to the
248 <constant>AF_UNIX</constant> socket referenced in the
249 <varname>$NOTIFY_SOCKET</varname> environment
250 variable. If the first character of
251 <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is
252 understood as Linux abstract namespace socket. The
253 datagram is accompanied by the process credentials of
254 the sending service, using SCM_CREDENTIALS.</para>
258 <title>Environment</title>
260 <variablelist class='environment-variables'>
262 <term><varname>$NOTIFY_SOCKET</varname></term>
264 <listitem><para>Set by the service manager
265 for supervised processes for status
266 and start-up completion
267 notification. This environment variable
269 <function>sd_notify()</function> talks
270 to. See above for details.</para></listitem>
276 <title>Examples</title>
279 <title>Start-up Notification</title>
281 <para>When a service finished starting up, it
282 might issue the following call to notify
283 the service manager:</para>
285 <programlisting>sd_notify(0, "READY=1");</programlisting>
289 <title>Extended Start-up Notification</title>
291 <para>A service could send the following after
292 completing initialization:</para>
294 <programlisting>sd_notifyf(0, "READY=1\n"
295 "STATUS=Processing requests...\n"
297 (unsigned long) getpid());</programlisting>
301 <title>Error Cause Notification</title>
303 <para>A service could send the following shortly before exiting, on failure</para>
305 <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
308 errno);</programlisting>
313 <title>See Also</title>
315 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
316 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
317 <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
318 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
319 <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>