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.5/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 string.
 102     Most importantly, it can be used for start-up or reload completion notifications.</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 silently do nothing, and the variable is no longer inherited
 108     by child 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 see the next section
 113     for a list of assignments understood by the service manager.</para>
 114
 115     <para>Note that systemd will accept status data sent from a service only if the
 116     <varname>NotifyAccess=</varname> option is correctly set in the service definition file. See
 117     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 118     details.</para>
 119
 120     <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only
 121     if either the sending process is still around at the time PID 1 processes the message, or if the sending
 122     process is explicitly runtime-tracked by the service manager. The latter is the case if the service
 123     manager originally forked off the process, i.e. on all processes that match
 124     <varname>NotifyAccess=</varname><option>main</option> or
 125     <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit
 126     sends an <function>sd_notify()</function> message and immediately exits, the service manager might not be
 127     able to properly attribute the message to the unit, and thus will ignore it, even if
 128     <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
 129
 130     <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of
 131     notifications to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as
 132     a synchronization point and ensures all notifications sent before this call have been picked up by the
 133     service manager when it returns successfully. Use of <function>sd_notify_barrier()</function> is needed
 134     for clients which are not invoked by the service manager, otherwise this synchronization mechanism is
 135     unnecessary for attribution of notifications to the unit.</para>
 136
 137     <para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a
 138     <function>printf()</function>-like format string plus arguments.</para>
 139
 140     <para><function>sd_pid_notify()</function> and <function>sd_pid_notifyf()</function> are similar to
 141     <function>sd_notify()</function> and <function>sd_notifyf()</function> but take a process ID (PID) to use
 142     as originating PID for the message as first argument. This is useful to send notification messages on
 143     behalf of other processes, provided the appropriate privileges are available. If the PID argument is
 144     specified as 0, the process ID of the calling process is used, in which case the calls are fully
 145     equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para>
 146
 147     <para><function>sd_pid_notify_with_fds()</function> is similar to <function>sd_pid_notify()</function>
 148     but takes an additional array of file descriptors. These file descriptors are sent along the notification
 149     message to the service manager. This is particularly useful for sending <literal>FDSTORE=1</literal>
 150     messages, as described above. The additional arguments are a pointer to the file descriptor array plus
 151     the number of file descriptors in the array. If the number of file descriptors is passed as 0, the call
 152     is fully equivalent to <function>sd_pid_notify()</function>, i.e. no file descriptors are passed. Note
 153     that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
 154     immediately closed on reception.</para>
 155
 156     <para><function>sd_pid_notifyf_with_fds()</function> is a combination of
 157     <function>sd_pid_notify_with_fds()</function> and <function>sd_notifyf()</function>, i.e. it accepts both
 158     a PID and a set of file descriptors as input, and processes a format string to generate the state
 159     string.</para>
 160
 161     <para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of
 162     previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a
 163     relative <varname>timeout</varname> value in microseconds which is passed to
 164     <citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
 165     </citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.</para>
 166
 167     <para><function>sd_pid_notify_barrier()</function> is just like <function>sd_notify_barrier()</function>,
 168     but allows specifying the originating PID for the notification message.</para>
 169   </refsect1>
 170
 171   <refsect1>
 172     <title>Well-known assignments</title>
 173
 174     <para>The following assignments have a defined meaning:</para>
 175
 176     <variablelist>
 177       <varlistentry>
 178         <term>READY=1</term>
 179
 180         <listitem><para>Tells the service manager that service startup is finished, or the service finished
 181         re-loading its configuration. This is only used by systemd if the service definition file has
 182         <varname>Type=notify</varname> or <varname>Type=notify-reload</varname> set. Since there is little
 183         value in signaling non-readiness, the only value services should send is <literal>READY=1</literal>
 184         (i.e.  <literal>READY=0</literal> is not defined).</para></listitem>
 185       </varlistentry>
 186
 187       <varlistentry>
 188         <term>RELOADING=1</term>
 189
 190         <listitem><para>Tells the service manager that the service is beginning to reload its configuration.
 191         This is useful to allow the service manager to track the service's internal state, and present it to
 192         the user. Note that a service that sends this notification must also send a
 193         <literal>READY=1</literal> notification when it completed reloading its configuration. Reloads the
 194         service manager is notified about with this mechanisms are propagated in the same way as they are
 195         when originally initiated through the service manager. This message is particularly relevant for
 196         <varname>Type=notify-reload</varname> services, to inform the service manager that the request to
 197         reload the service has been received and is now being processed.</para>
 198
 199         <xi:include href="version-info.xml" xpointer="v217"/></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term>STOPPING=1</term>
 204
 205         <listitem><para>Tells the service manager that the service is beginning its shutdown. This is useful
 206         to allow the service manager to track the service's internal state, and present it to the user.
 207         </para>
 208
 209         <xi:include href="version-info.xml" xpointer="v217"/></listitem>
 210       </varlistentry>
 211
 212       <varlistentry>
 213         <term>MONOTONIC_USEC=…</term>
 214
 215         <listitem><para>A field carrying the monotonic timestamp (as per
 216         <constant>CLOCK_MONOTONIC</constant>) formatted in decimal in μs, when the notification message was
 217         generated by the client. This is typically used in combination with <literal>RELOADING=1</literal>,
 218         to allow the service manager to properly synchronize reload cycles. See
 219         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 220         for details, specifically <literal>Type=notify-reload</literal>.</para>
 221
 222         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term>STATUS=…</term>
 227
 228         <listitem><para>Passes a single-line UTF-8 status string back to the service manager that describes
 229         the service state. This is free-form and can be used for various purposes: general state feedback,
 230         fsck-like programs could pass completion percentages and failing programs could pass a human-readable
 231         error message. Example: <literal>STATUS=Completed 66% of file system check…</literal></para>
 232
 233         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term>NOTIFYACCESS=…</term>
 238
 239         <listitem><para>Reset the access to the service status notification socket during runtime, overriding
 240         <varname>NotifyAccess=</varname> setting in the service unit file. See
 241         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 242         for details, specifically <literal>NotifyAccess=</literal> for a list of accepted values.
 243         </para>
 244
 245         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term>ERRNO=…</term>
 250
 251         <listitem><para>If a service fails, the errno-style error code, formatted as string. Example:
 252         <literal>ERRNO=2</literal> for ENOENT.</para>
 253
 254         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 255       </varlistentry>
 256
 257       <varlistentry>
 258         <term>BUSERROR=…</term>
 259
 260         <listitem><para>If a service fails, the D-Bus error-style error code. Example:
 261         <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal>. Note that this assignment is
 262         currently not used by <command>systemd</command>.</para>
 263
 264         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term>EXIT_STATUS=…</term>
 269
 270         <listitem><para>The exit status of a service or the manager itself. Note that
 271         <command>systemd</command> currently does not consume this value when sent by services, so this
 272         assignment is only informational. The manager will send this notification to <emphasis>its</emphasis>
 273         notification socket, which may be used to collect an exit status from the system (a container or
 274         VM) as it shuts down. For example,
 275         <citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 276         makes use of this. The value to return may be set via the
 277         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 278         <command>exit</command> verb.</para>
 279
 280         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term>MAINPID=…</term>
 285
 286         <listitem><para>The main process ID (PID) of the service, in case the service manager did not fork
 287         off the process itself. Example: <literal>MAINPID=4711</literal>.</para>
 288
 289         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term>WATCHDOG=1</term>
 294
 295         <listitem><para>Tells the service manager to update the watchdog timestamp. This is the keep-alive
 296         ping that services need to issue in regular intervals if <varname>WatchdogSec=</varname> is enabled
 297         for it. See
 298         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 299         for information how to enable this functionality and
 300         <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 301         for the details of how the service can check whether the watchdog is enabled. </para></listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term>WATCHDOG=trigger</term>
 306
 307         <listitem><para>Tells the service manager that the service detected an internal error that should be
 308         handled by the configured watchdog options. This will trigger the same behaviour as if
 309         <varname>WatchdogSec=</varname> is enabled and the service did not send <literal>WATCHDOG=1</literal>
 310         in time. Note that <varname>WatchdogSec=</varname> does not need to be enabled for
 311         <literal>WATCHDOG=trigger</literal> to trigger the watchdog action. See
 312         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 313         for information about the watchdog behavior. </para>
 314
 315         <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 316       </varlistentry>
 317
 318       <varlistentry>
 319         <term>WATCHDOG_USEC=…</term>
 320
 321         <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.  Notice that this is not
 322         available when using <function>sd_event_set_watchdog()</function> or
 323         <function>sd_watchdog_enabled()</function>.  Example :
 324         <literal>WATCHDOG_USEC=20000000</literal></para>
 325
 326         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 327       </varlistentry>
 328
 329       <varlistentry>
 330         <term>EXTEND_TIMEOUT_USEC=…</term>
 331
 332         <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
 333         corresponding the current state. The value specified is a time in microseconds during which the
 334         service must send a new message. A service timeout will occur if the message isn't received, but only
 335         if the runtime of the current state is beyond the original maximum times of
 336         <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, and
 337         <varname>TimeoutStopSec=</varname>.  See
 338         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 339         for effects on the service timeouts.</para>
 340
 341         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <term>FDSTORE=1</term>
 346
 347         <listitem><para>Store file descriptors in the service manager. File descriptors sent this way will be
 348         held for the service by the service manager and will later be handed back using the usual file
 349         descriptor passing logic at the next start or restart of the service, see
 350         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 351         Any open sockets and other file descriptors which should not be closed during a restart may be stored
 352         this way. When a service is stopped, its file descriptor store is discarded and all file descriptors
 353         in it are closed, except when overridden with <varname>FileDescriptorStorePreserve=</varname>, see
 354         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 355         </para>
 356
 357         <para>The service manager will accept messages for a service only if its
 358         <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
 359         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 360         The service manager will set the <varname>$FDSTORE</varname> environment variable for services that
 361         have the file descriptor store enabled, see
 362         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 363         </para>
 364
 365         <para>If <varname>FDPOLL=0</varname> is not set and the file descriptors are pollable (see
 366         <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then
 367         any <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in
 368         their automatic removal from the store.</para>
 369
 370         <para>Multiple sets of file descriptors may be sent in separate messages, in which case the sets are
 371         combined. The service manager removes duplicate file descriptors (those pointing to the same object)
 372         before passing them to the service.</para>
 373
 374         <para>This functionality should be used to implement services that can restart after an explicit
 375         request or a crash without losing state. Application state can either be serialized to a file in
 376         <filename>/run/</filename>, or better, stored in a
 377         <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 378         memory file descriptor. Use <function>sd_pid_notify_with_fds()</function> to send messages with
 379         <literal>FDSTORE=1</literal>. It is recommended to combine <varname>FDSTORE=</varname> with
 380         <varname>FDNAME=</varname> to make it easier to manage the stored file descriptors.</para>
 381
 382         <para>For further information on the file descriptor store see the <ulink
 383         url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview.</para>
 384
 385         <xi:include href="version-info.xml" xpointer="v219"/></listitem>
 386       </varlistentry>
 387
 388       <varlistentry>
 389         <term>FDSTOREREMOVE=1</term>
 390
 391         <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be
 392         combined with <varname>FDNAME=</varname> to specify the name of the file descriptors to
 393         remove.</para>
 394
 395         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 396       </varlistentry>
 397
 398       <varlistentry>
 399         <term>FDNAME=…</term>
 400
 401         <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the
 402         submitted file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for
 403         the file descriptors to remove. This name is passed to the service during activation, and may be
 404         queried using
 405         <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 406         File descriptors submitted without this field will be called <literal>stored</literal>.</para>
 407
 408         <para>The name may consist of arbitrary ASCII characters except control characters or
 409         <literal>:</literal>. It may not be longer than 255 characters. If a submitted name does not follow
 410         these restrictions, it is ignored.</para>
 411
 412         <para>Note that if multiple file descriptors are submitted in a single message, the specified name
 413         will be used for all of them. In order to assign different names to submitted file descriptors,
 414         submit them in separate messages.</para>
 415
 416         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 417       </varlistentry>
 418
 419       <varlistentry>
 420         <term>FDPOLL=0</term>
 421
 422         <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the
 423         submitted file descriptors regardless of whether or not they are pollable. As this option disables
 424         automatic cleanup of the submitted file descriptors on EPOLLERR and EPOLLHUP, care must be taken to
 425         ensure proper manual cleanup.  Use of this option is not generally recommended except for when
 426         automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the
 427         store.</para>
 428
 429         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 430       </varlistentry>
 431
 432       <varlistentry>
 433         <term>BARRIER=1</term>
 434
 435         <listitem><para>Tells the service manager that the client is explicitly requesting synchronization by
 436         means of closing the file descriptor sent with this command. The service manager guarantees that the
 437         processing of a <varname>BARRIER=1</varname> command will only happen after all previous notification
 438         messages sent before this command have been processed. Hence, this command accompanied with a single
 439         file descriptor can be used to synchronize against reception of all previous status messages. Note
 440         that this command cannot be mixed with other notifications, and has to be sent in a separate message
 441         to the service manager, otherwise all assignments will be ignored. Note that sending 0 or more than 1
 442         file descriptor with this command is a violation of the protocol.</para>
 443
 444         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 445       </varlistentry>
 446     </variablelist>
 447
 448     <para>The notification messages sent by services are interpreted by the service manager. Unknown
 449     assignments are ignored. Thus, it is safe (but often without effect) to send assignments which are not
 450     in this list. The protocol is extensible, but care should be taken to ensure private extensions are
 451     recognizable as such. Specifically, it is recommend to prefix them with <literal>X_</literal> followed by
 452     some namespace identifier. The service manager also sends some messages to <emphasis>its</emphasis>
 453     notification socket, which may then consumed by a supervising machine or container manager further up the
 454     stack. The service manager sends a number of extension fields, for example
 455     <varname>X_SYSTEMD_UNIT_ACTIVE=</varname>, for details see
 456     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 457   </refsect1>
 458
 459   <refsect1>
 460     <title>Return Value</title>
 461
 462     <para>On failure, these calls return a negative errno-style error code. If
 463     <varname>$NOTIFY_SOCKET</varname> was not set and hence no status message could be sent, 0 is
 464     returned. If the status was sent, these functions return a positive value. In order to support both
 465     service managers that implement this scheme and those which do not, it is generally recommended to ignore
 466     the return value of this call. Note that the return value simply indicates whether the notification
 467     message was enqueued properly, it does not reflect whether the message could be processed
 468     successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
 469     <varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file
 470     descriptors (see above).</para>
 471   </refsect1>
 472
 473   <refsect1>
 474     <title>Notes</title>
 475
 476     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 477     <xi:include href="threads-aware.xml" xpointer="getenv"/>
 478
 479     <para>These functions send a single datagram with the state string as payload to the socket referenced in
 480     the <varname>$NOTIFY_SOCKET</varname> environment variable. If the first character of
 481     <varname>$NOTIFY_SOCKET</varname> is <literal>/</literal> or <literal>@</literal>, the string is
 482     understood as an <constant>AF_UNIX</constant> or Linux abstract namespace socket (respectively), and in
 483     both cases the datagram is accompanied by the process credentials of the sending service, using
 484     SCM_CREDENTIALS. If the string starts with <literal>vsock:</literal> then the string is understood as an
 485     <constant>AF_VSOCK</constant> address, which is useful for hypervisors/VMMs or other processes on the
 486     host to receive a notification when a virtual machine has finished booting. Note that in case the
 487     hypervisor does not support <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>,
 488     <constant>SOCK_SEQPACKET</constant> will be used instead. <literal>vsock-stream</literal>,
 489     <literal>vsock-dgram</literal> and <literal>vsock-seqpacket</literal> can be used instead of
 490     <literal>vsock</literal> to force usage of the corresponding socket type. The address should be in the
 491     form: <literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock, the CID is mandatory and
 492     cannot be <literal>VMADDR_CID_ANY</literal>.  Note that PID1 will send the VSOCK packets from a
 493     privileged port (i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in
 494     the guest might try to send malicious notifications to the host, driving it to make destructive decisions
 495     based on them.</para>
 496
 497     <refsect2>
 498       <title>Standalone Implementations</title>
 499       <para>Note that, while using this library should be preferred in order to avoid code duplication, it is
 500       also possible to reimplement the simple readiness notification protocol without external dependencies,
 501       as demonstrated in the following self-contained examples from several languages:</para>
 502       <refsect3>
 503         <title>C</title>
 504         <programlisting><xi:include href="notify-selfcontained-example.c" parse="text"/></programlisting>
 505       </refsect3>
 506       <refsect3>
 507         <title>Python</title>
 508         <programlisting><xi:include href="notify-selfcontained-example.py" parse="text"/></programlisting>
 509       </refsect3>
 510     </refsect2>
 511   </refsect1>
 512
 513   <refsect1>
 514     <title>Environment</title>
 515
 516     <variablelist class='environment-variables'>
 517       <varlistentry>
 518         <term><varname>$NOTIFY_SOCKET</varname></term>
 519
 520         <listitem><para>Set by the service manager for supervised processes for status and start-up
 521         completion notification.  This environment variable specifies the socket
 522         <function>sd_notify()</function> talks to. See above for details.</para></listitem>
 523       </varlistentry>
 524     </variablelist>
 525   </refsect1>
 526
 527   <refsect1>
 528     <title>Examples</title>
 529
 530     <example>
 531       <title>Start-up Notification</title>
 532
 533       <para>When a service finished starting up, it might issue the following call to notify the service
 534       manager:</para>
 535
 536       <programlisting>sd_notify(0, "READY=1");</programlisting>
 537     </example>
 538
 539     <example>
 540       <title>Extended Start-up Notification</title>
 541
 542       <para>A service could send the following after completing initialization:</para>
 543
 544       <programlisting>
 545 sd_notifyf(0, "READY=1\n"
 546               "STATUS=Processing requests…\n"
 547               "MAINPID=%lu",
 548            (unsigned long) getpid());</programlisting>
 549     </example>
 550
 551     <example>
 552       <title>Error Cause Notification</title>
 553
 554       <para>A service could send the following shortly before exiting, on failure:</para>
 555
 556       <programlisting>
 557 sd_notifyf(0, "STATUS=Failed to start up: %s\n"
 558               "ERRNO=%i",
 559            strerror_r(errnum, (char[1024]){}, 1024),
 560            errnum);</programlisting>
 561     </example>
 562
 563     <example>
 564       <title>Store a File Descriptor in the Service Manager</title>
 565
 566       <para>To store an open file descriptor in the service manager, in order to continue operation after a
 567       service restart without losing state, use <literal>FDSTORE=1</literal>:</para>
 568
 569       <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &amp;fd, 1);</programlisting>
 570     </example>
 571
 572     <example>
 573       <title>Eliminating race conditions</title>
 574
 575       <para>When the client sending the notifications is not spawned by the service manager, it may exit too
 576       quickly and the service manager may fail to attribute them correctly to the unit. To prevent such
 577       races, use <function>sd_notify_barrier()</function> to synchronize against reception of all
 578       notifications sent before this call is made.</para>
 579
 580       <programlisting>
 581 sd_notify(0, "READY=1");
 582 /* set timeout to 5 seconds */
 583 sd_notify_barrier(0, 5 * 1000000);
 584       </programlisting>
 585     </example>
 586   </refsect1>
 587
 588   <refsect1>
 589     <title>History</title>
 590     <para><function>sd_pid_notify()</function>,
 591     <function>sd_pid_notifyf()</function>, and
 592     <function>sd_pid_notify_with_fds()</function> were added in version 219.</para>
 593     <para><function>sd_notify_barrier()</function> was added in version 246.</para>
 594     <para><function>sd_pid_notifyf_with_fds()</function> and
 595     <function>sd_pid_notify_barrier()</function> were added in version 254.</para>
 596   </refsect1>
 597
 598   <refsect1>
 599     <title>See Also</title>
 600     <para><simplelist type="inline">
 601       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 602       <member><citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 603       <member><citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 604       <member><citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 605       <member><citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 606       <member><citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 607       <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 608     </simplelist></para>
 609   </refsect1>
 610
 611 </refentry>