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