]>
Commit | Line | Data |
---|---|---|
514094f9 | 1 | <?xml version='1.0'?> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
12b42c76 | 3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
0307f791 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
f9378423 | 5 | |
6a70f3aa | 6 | <refentry id="sd_notify" |
798d3a52 ZJS |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> |
8 | ||
9 | <refentryinfo> | |
10 | <title>sd_notify</title> | |
11 | <productname>systemd</productname> | |
798d3a52 ZJS |
12 | </refentryinfo> |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>sd_notify</refentrytitle> | |
16 | <manvolnum>3</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>sd_notify</refname> | |
21 | <refname>sd_notifyf</refname> | |
22 | <refname>sd_pid_notify</refname> | |
23 | <refname>sd_pid_notifyf</refname> | |
24 | <refname>sd_pid_notify_with_fds</refname> | |
4f07ddfa | 25 | <refname>sd_notify_barrier</refname> |
798d3a52 ZJS |
26 | <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> |
27 | </refnamediv> | |
28 | ||
29 | <refsynopsisdiv> | |
30 | <funcsynopsis> | |
31 | <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> | |
32 | ||
33 | <funcprototype> | |
34 | <funcdef>int <function>sd_notify</function></funcdef> | |
35 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
36 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
37 | </funcprototype> | |
38 | ||
39 | <funcprototype> | |
40 | <funcdef>int <function>sd_notifyf</function></funcdef> | |
41 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
42 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
1eecafb8 | 43 | <paramdef>…</paramdef> |
798d3a52 ZJS |
44 | </funcprototype> |
45 | ||
46 | <funcprototype> | |
47 | <funcdef>int <function>sd_pid_notify</function></funcdef> | |
48 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
49 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
50 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
51 | </funcprototype> | |
52 | ||
53 | <funcprototype> | |
54 | <funcdef>int <function>sd_pid_notifyf</function></funcdef> | |
55 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
56 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
57 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
1eecafb8 | 58 | <paramdef>…</paramdef> |
798d3a52 ZJS |
59 | </funcprototype> |
60 | ||
61 | <funcprototype> | |
62 | <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> | |
63 | <paramdef>pid_t <parameter>pid</parameter></paramdef> | |
64 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
65 | <paramdef>const char *<parameter>state</parameter></paramdef> | |
66 | <paramdef>const int *<parameter>fds</parameter></paramdef> | |
67 | <paramdef>unsigned <parameter>n_fds</parameter></paramdef> | |
68 | </funcprototype> | |
4f07ddfa KKD |
69 | |
70 | <funcprototype> | |
71 | <funcdef>int <function>sd_notify_barrier</function></funcdef> | |
72 | <paramdef>int <parameter>unset_environment</parameter></paramdef> | |
73 | <paramdef>uint64_t <parameter>timeout</parameter></paramdef> | |
74 | </funcprototype> | |
798d3a52 ZJS |
75 | </funcsynopsis> |
76 | </refsynopsisdiv> | |
77 | ||
78 | <refsect1> | |
79 | <title>Description</title> | |
80 | <para><function>sd_notify()</function> may be called by a service | |
81 | to notify the service manager about state changes. It can be used | |
82 | to send arbitrary information, encoded in an | |
b938cb90 | 83 | environment-block-like string. Most importantly, it can be used for |
798d3a52 ZJS |
84 | start-up completion notification.</para> |
85 | ||
86 | <para>If the <parameter>unset_environment</parameter> parameter is | |
87 | non-zero, <function>sd_notify()</function> will unset the | |
88 | <varname>$NOTIFY_SOCKET</varname> environment variable before | |
89 | returning (regardless of whether the function call itself | |
90 | succeeded or not). Further calls to | |
91 | <function>sd_notify()</function> will then fail, but the variable | |
92 | is no longer inherited by child processes.</para> | |
93 | ||
94 | <para>The <parameter>state</parameter> parameter should contain a | |
95 | newline-separated list of variable assignments, similar in style | |
96 | to an environment block. A trailing newline is implied if none is | |
97 | specified. The string may contain any kind of variable | |
98 | assignments, but the following shall be considered | |
99 | well-known:</para> | |
100 | ||
101 | <variablelist> | |
102 | <varlistentry> | |
103 | <term>READY=1</term> | |
104 | ||
8d1ab18a LP |
105 | <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its |
106 | configuration. This is only used by systemd if the service definition file has <varname>Type=notify</varname> | |
107 | set. Since there is little value in signaling non-readiness, the only value services should send is | |
108 | <literal>READY=1</literal> (i.e. <literal>READY=0</literal> is not defined).</para></listitem> | |
798d3a52 ZJS |
109 | </varlistentry> |
110 | ||
111 | <varlistentry> | |
112 | <term>RELOADING=1</term> | |
113 | ||
114 | <listitem><para>Tells the service manager that the service is | |
115 | reloading its configuration. This is useful to allow the | |
116 | service manager to track the service's internal state, and | |
117 | present it to the user. Note that a service that sends this | |
118 | notification must also send a <literal>READY=1</literal> | |
119 | notification when it completed reloading its | |
15d167f8 JW |
120 | configuration. Reloads are propagated in the same way as they |
121 | are when initiated by the user.</para></listitem> | |
798d3a52 ZJS |
122 | </varlistentry> |
123 | ||
124 | <varlistentry> | |
125 | <term>STOPPING=1</term> | |
126 | ||
127 | <listitem><para>Tells the service manager that the service is | |
128 | beginning its shutdown. This is useful to allow the service | |
129 | manager to track the service's internal state, and present it | |
130 | to the user.</para></listitem> | |
131 | </varlistentry> | |
132 | ||
133 | <varlistentry> | |
1eecafb8 | 134 | <term>STATUS=…</term> |
798d3a52 ZJS |
135 | |
136 | <listitem><para>Passes a single-line UTF-8 status string back | |
137 | to the service manager that describes the service state. This | |
138 | is free-form and can be used for various purposes: general | |
139 | state feedback, fsck-like programs could pass completion | |
b938cb90 | 140 | percentages and failing programs could pass a human-readable |
798d3a52 | 141 | error message. Example: <literal>STATUS=Completed 66% of file |
1eecafb8 | 142 | system check…</literal></para></listitem> |
798d3a52 ZJS |
143 | </varlistentry> |
144 | ||
145 | <varlistentry> | |
1eecafb8 | 146 | <term>ERRNO=…</term> |
798d3a52 ZJS |
147 | |
148 | <listitem><para>If a service fails, the errno-style error | |
149 | code, formatted as string. Example: <literal>ERRNO=2</literal> | |
150 | for ENOENT.</para></listitem> | |
151 | </varlistentry> | |
152 | ||
153 | <varlistentry> | |
1eecafb8 | 154 | <term>BUSERROR=…</term> |
798d3a52 ZJS |
155 | |
156 | <listitem><para>If a service fails, the D-Bus error-style | |
157 | error code. Example: | |
158 | <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> | |
159 | </varlistentry> | |
160 | ||
161 | <varlistentry> | |
1eecafb8 | 162 | <term>MAINPID=…</term> |
798d3a52 ZJS |
163 | |
164 | <listitem><para>The main process ID (PID) of the service, in | |
165 | case the service manager did not fork off the process itself. | |
166 | Example: <literal>MAINPID=4711</literal></para></listitem> | |
167 | </varlistentry> | |
168 | ||
169 | <varlistentry> | |
170 | <term>WATCHDOG=1</term> | |
171 | ||
172 | <listitem><para>Tells the service manager to update the | |
173 | watchdog timestamp. This is the keep-alive ping that services | |
174 | need to issue in regular intervals if | |
175 | <varname>WatchdogSec=</varname> is enabled for it. See | |
176 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
177 | for information how to enable this functionality and | |
178 | <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
1d3eaa93 | 179 | for the details of how the service can check whether the |
798d3a52 ZJS |
180 | watchdog is enabled. </para></listitem> |
181 | </varlistentry> | |
182 | ||
99b43caf JK |
183 | <varlistentry> |
184 | <term>WATCHDOG=trigger</term> | |
185 | ||
186 | <listitem><para>Tells the service manager that the service detected an internal error that should be handled by | |
187 | the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is | |
188 | enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that | |
189 | <varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger | |
190 | the watchdog action. See | |
191 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for | |
192 | information about the watchdog behavior. </para></listitem> | |
193 | </varlistentry> | |
194 | ||
c45d11cb LP |
195 | <varlistentry> |
196 | <term>WATCHDOG_USEC=…</term> | |
197 | ||
198 | <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. | |
199 | Notice that this is not available when using <function>sd_event_set_watchdog()</function> | |
200 | or <function>sd_watchdog_enabled()</function>. | |
201 | Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> | |
202 | </varlistentry> | |
798d3a52 | 203 | |
a327431b DB |
204 | <varlistentry> |
205 | <term>EXTEND_TIMEOUT_USEC=…</term> | |
206 | ||
207 | <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout | |
208 | corresponding the current state. The value specified is a time in microseconds during which the service must | |
209 | send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the | |
e69cacd2 | 210 | current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, |
a327431b DB |
211 | and <varname>TimeoutStopSec=</varname>. |
212 | See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
213 | for effects on the service timeouts.</para></listitem> | |
214 | </varlistentry> | |
215 | ||
798d3a52 ZJS |
216 | <varlistentry> |
217 | <term>FDSTORE=1</term> | |
218 | ||
3ceb72e5 LP |
219 | <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this way will |
220 | be maintained per-service by the service manager and will later be handed back using the usual file descriptor | |
221 | passing logic at the next invocation of the service, see | |
222 | <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This is | |
223 | useful for implementing services that can restart after an explicit request or a crash without losing | |
224 | state. Any open sockets and other file descriptors which should not be closed during the restart may be stored | |
225 | this way. Application state can either be serialized to a file in <filename>/run</filename>, or better, stored | |
226 | in a <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> memory | |
227 | file descriptor. Note that the service manager will accept messages for a service only if its | |
228 | <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see | |
cb5a46b8 KL |
229 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If |
230 | <varname>FDPOLL=0</varname> is not set and the file descriptors sent are pollable (see | |
3ceb72e5 LP |
231 | <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then any |
232 | <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in their | |
233 | automatic removal from the store. Multiple arrays of file descriptors may be sent in separate messages, in | |
234 | which case the arrays are combined. Note that the service manager removes duplicate (pointing to the same | |
235 | object) file descriptors before passing them to the service. Use <function>sd_pid_notify_with_fds()</function> | |
236 | to send messages with <literal>FDSTORE=1</literal>, see below.</para></listitem> | |
798d3a52 ZJS |
237 | </varlistentry> |
238 | ||
e78ee06d LP |
239 | <varlistentry> |
240 | <term>FDSTOREREMOVE=1</term> | |
241 | ||
242 | <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with | |
243 | <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem> | |
244 | </varlistentry> | |
245 | ||
8dd4c05b | 246 | <varlistentry> |
1eecafb8 | 247 | <term>FDNAME=…</term> |
8dd4c05b | 248 | |
e78ee06d LP |
249 | <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted |
250 | file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file | |
251 | descriptors to remove. This name is passed to the service during activation, and may be queried using | |
8dd4c05b | 252 | <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File |
e78ee06d LP |
253 | descriptors submitted without this field set, will implicitly get the name <literal>stored</literal> |
254 | assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to | |
255 | all of them. In order to assign different names to submitted file descriptors, submit them in separate | |
256 | invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII | |
257 | characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a | |
258 | submitted name does not follow these restrictions, it is ignored.</para></listitem> | |
8dd4c05b LP |
259 | </varlistentry> |
260 | ||
cb5a46b8 KL |
261 | <varlistentry> |
262 | <term>FDPOLL=0</term> | |
263 | ||
264 | <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored | |
265 | file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup | |
266 | of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup. | |
267 | Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such | |
268 | as prematurely discarding file descriptors from the store.</para></listitem> | |
269 | </varlistentry> | |
270 | ||
4f07ddfa KKD |
271 | <varlistentry> |
272 | <term>BARRIER=1</term> | |
273 | ||
274 | <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by means of | |
2d4f8cf4 | 275 | closing the file descriptor sent with this command. The service manager guarantees that the processing of a <varname> |
4f07ddfa KKD |
276 | BARRIER=1</varname> command will only happen after all previous notification messages sent before this command |
277 | have been processed. Hence, this command accompanied with a single file descriptor can be used to synchronize | |
278 | against reception of all previous status messages. Note that this command cannot be mixed with other notifications, | |
279 | and has to be sent in a separate message to the service manager, otherwise all assignments will be ignored. Note that | |
280 | sending 0 or more than 1 file descriptor with this command is a violation of the protocol.</para></listitem> | |
281 | </varlistentry> | |
798d3a52 ZJS |
282 | </variablelist> |
283 | ||
284 | <para>It is recommended to prefix variable names that are not | |
285 | listed above with <varname>X_</varname> to avoid namespace | |
286 | clashes.</para> | |
287 | ||
288 | <para>Note that systemd will accept status data sent from a | |
289 | service only if the <varname>NotifyAccess=</varname> option is | |
290 | correctly set in the service definition file. See | |
291 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
292 | for details.</para> | |
293 | ||
b3bb6476 LP |
294 | <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either |
295 | the sending process is still around at the time PID 1 processes the message, or if the sending process is | |
296 | explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked | |
297 | off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or | |
298 | <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an | |
299 | <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly | |
300 | attribute the message to the unit, and thus will ignore it, even if | |
301 | <varname>NotifyAccess=</varname><option>all</option> is set for it.</para> | |
302 | ||
4f07ddfa KKD |
303 | <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications |
304 | to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point | |
305 | and ensures all notifications sent before this call have been picked up by the service manager when it returns | |
306 | successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the | |
307 | service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the | |
308 | unit.</para> | |
309 | ||
798d3a52 ZJS |
310 | <para><function>sd_notifyf()</function> is similar to |
311 | <function>sd_notify()</function> but takes a | |
312 | <function>printf()</function>-like format string plus | |
313 | arguments.</para> | |
314 | ||
315 | <para><function>sd_pid_notify()</function> and | |
316 | <function>sd_pid_notifyf()</function> are similar to | |
317 | <function>sd_notify()</function> and | |
318 | <function>sd_notifyf()</function> but take a process ID (PID) to | |
319 | use as originating PID for the message as first argument. This is | |
320 | useful to send notification messages on behalf of other processes, | |
321 | provided the appropriate privileges are available. If the PID | |
b938cb90 | 322 | argument is specified as 0, the process ID of the calling process |
798d3a52 ZJS |
323 | is used, in which case the calls are fully equivalent to |
324 | <function>sd_notify()</function> and | |
325 | <function>sd_notifyf()</function>.</para> | |
326 | ||
327 | <para><function>sd_pid_notify_with_fds()</function> is similar to | |
328 | <function>sd_pid_notify()</function> but takes an additional array | |
329 | of file descriptors. These file descriptors are sent along the | |
330 | notification message to the service manager. This is particularly | |
331 | useful for sending <literal>FDSTORE=1</literal> messages, as | |
332 | described above. The additional arguments are a pointer to the | |
333 | file descriptor array plus the number of file descriptors in the | |
334 | array. If the number of file descriptors is passed as 0, the call | |
335 | is fully equivalent to <function>sd_pid_notify()</function>, i.e. | |
336 | no file descriptors are passed. Note that sending file descriptors | |
337 | to the service manager on messages that do not expect them (i.e. | |
338 | without <literal>FDSTORE=1</literal>) they are immediately closed | |
339 | on reception.</para> | |
4f07ddfa KKD |
340 | |
341 | <para><function>sd_notify_barrier()</function> allows the caller to | |
342 | synchronize against reception of previously sent notification messages | |
343 | and uses the <literal>BARRIER=1</literal> command. It takes a relative | |
344 | <varname>timeout</varname> value in microseconds which is passed to | |
345 | <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum> | |
346 | </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout. | |
347 | </para> | |
798d3a52 ZJS |
348 | </refsect1> |
349 | ||
350 | <refsect1> | |
351 | <title>Return Value</title> | |
352 | ||
3ceb72e5 LP |
353 | <para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was |
354 | not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a | |
355 | positive value. In order to support both service managers that implement this scheme and those which do not, it is | |
356 | generally recommended to ignore the return value of this call. Note that the return value simply indicates whether | |
357 | the notification message was enqueued properly, it does not reflect whether the message could be processed | |
358 | successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using | |
359 | <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see | |
360 | above).</para> | |
798d3a52 ZJS |
361 | </refsect1> |
362 | ||
363 | <refsect1> | |
364 | <title>Notes</title> | |
365 | ||
366 | <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> | |
367 | ||
3122633a | 368 | <para>These functions send a single datagram with the |
798d3a52 ZJS |
369 | state string as payload to the <constant>AF_UNIX</constant> socket |
370 | referenced in the <varname>$NOTIFY_SOCKET</varname> environment | |
371 | variable. If the first character of | |
372 | <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the | |
373 | string is understood as Linux abstract namespace socket. The | |
374 | datagram is accompanied by the process credentials of the sending | |
375 | service, using SCM_CREDENTIALS.</para> | |
376 | </refsect1> | |
377 | ||
378 | <refsect1> | |
379 | <title>Environment</title> | |
380 | ||
381 | <variablelist class='environment-variables'> | |
382 | <varlistentry> | |
383 | <term><varname>$NOTIFY_SOCKET</varname></term> | |
384 | ||
385 | <listitem><para>Set by the service manager for supervised | |
386 | processes for status and start-up completion notification. | |
387 | This environment variable specifies the socket | |
388 | <function>sd_notify()</function> talks to. See above for | |
389 | details.</para></listitem> | |
390 | </varlistentry> | |
391 | </variablelist> | |
392 | </refsect1> | |
393 | ||
394 | <refsect1> | |
395 | <title>Examples</title> | |
396 | ||
397 | <example> | |
398 | <title>Start-up Notification</title> | |
399 | ||
400 | <para>When a service finished starting up, it might issue the | |
401 | following call to notify the service manager:</para> | |
402 | ||
403 | <programlisting>sd_notify(0, "READY=1");</programlisting> | |
404 | </example> | |
405 | ||
406 | <example> | |
407 | <title>Extended Start-up Notification</title> | |
408 | ||
409 | <para>A service could send the following after completing | |
410 | initialization:</para> | |
411 | ||
412 | <programlisting>sd_notifyf(0, "READY=1\n" | |
1eecafb8 | 413 | "STATUS=Processing requests…\n" |
798d3a52 ZJS |
414 | "MAINPID=%lu", |
415 | (unsigned long) getpid());</programlisting> | |
416 | </example> | |
417 | ||
418 | <example> | |
419 | <title>Error Cause Notification</title> | |
420 | ||
421 | <para>A service could send the following shortly before exiting, on failure:</para> | |
422 | ||
423 | <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" | |
424 | "ERRNO=%i", | |
425 | strerror(errno), | |
426 | errno);</programlisting> | |
427 | </example> | |
428 | ||
429 | <example> | |
430 | <title>Store a File Descriptor in the Service Manager</title> | |
431 | ||
432 | <para>To store an open file descriptor in the service manager, | |
433 | in order to continue operation after a service restart without | |
b938cb90 | 434 | losing state, use <literal>FDSTORE=1</literal>:</para> |
798d3a52 | 435 | |
8dd4c05b | 436 | <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting> |
798d3a52 | 437 | </example> |
4f07ddfa KKD |
438 | |
439 | <example> | |
440 | <title>Eliminating race conditions</title> | |
441 | ||
442 | <para>When the client sending the notifications is not spawned | |
443 | by the service manager, it may exit too quickly and the service | |
444 | manager may fail to attribute them correctly to the unit. To | |
445 | prevent such races, use <function>sd_notify_barrier()</function> | |
446 | to synchronize against reception of all notifications sent before | |
447 | this call is made.</para> | |
448 | ||
449 | <programlisting>sd_notify(0, "READY=1"); | |
450 | /* set timeout to 5 seconds */ | |
451 | sd_notify_barrier(0, 5 * 1000000); | |
452 | </programlisting> | |
453 | </example> | |
798d3a52 ZJS |
454 | </refsect1> |
455 | ||
456 | <refsect1> | |
457 | <title>See Also</title> | |
458 | <para> | |
459 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
460 | <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
8dd4c05b LP |
461 | <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
462 | <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
463 | <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
798d3a52 | 464 | <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, |
8dd4c05b | 465 | <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
798d3a52 ZJS |
466 | </para> |
467 | </refsect1> | |
f9378423 LP |
468 | |
469 | </refentry> |