man/sd_notify.xml

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