From: Luca Boccassi <bluca@debian.org>
Date: Mon, 18 Sep 2023 23:36:24 +0000 (+0100)
Subject: Merge pull request #29186 from keszybz/man-notifications-and-fd-store
X-Git-Tag: v255-rc1~510
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c2077ae0c43265cdc01c5a96b73f8acc8aa85445;p=thirdparty%2Fsystemd.git

Merge pull request #29186 from keszybz/man-notifications-and-fd-store

man: notifications and fd store
---

c2077ae0c43265cdc01c5a96b73f8acc8aa85445
diff --cc man/sd_notify.xml
index b75bf05808c,0f2f9314775..0476c579e77
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@@ -276,33 -344,41 +344,44 @@@
        <varlistentry>
          <term>FDSTORE=1</term>
  
-         <listitem><para>Stores additional file descriptors in the service manager. File descriptors sent this
-         way will be maintained per-service by the service manager and will later be handed back using the
-         usual file descriptor passing logic at the next invocation of the service (e.g. when it is
-         restarted), see
+         <listitem><para>Store file descriptors in the service manager. File descriptors sent this way will be
+         held for the service by the service manager and will later be handed back using the usual file
+         descriptor passing logic at the next start or restart of the service, see
          <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
-         This is useful for implementing services that can restart after an explicit request or a crash
-         without losing state. Any open sockets and other file descriptors which should not be closed during
-         the restart may be stored this way. Application state can either be serialized to a file in
-         <filename>/run/</filename>, or better, stored in a
-         <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
-         memory file descriptor. Note that the service manager will accept messages for a service only if its
+         Any open sockets and other file descriptors which should not be closed during a restart may be stored
+         this way. When a service is stopped, its file descriptor store is discarded and all file descriptors
+         in it are closed, except when overridden with <varname>FileDescriptorStorePreserve=</varname>, see
+         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+         </para>
+ 
+         <para>The service manager will accept messages for a service only if its
          <varname>FileDescriptorStoreMax=</varname> setting is non-zero (defaults to zero, see
-         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>). If
-         <varname>FDPOLL=0</varname> is not set and the file descriptors sent are pollable (see
+         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+         The service manager will set the <varname>$FDSTORE</varname> environment variable for services that
+         have the file descriptor store enabled, see
+         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+         </para>
+ 
+         <para>If <varname>FDPOLL=0</varname> is not set and the file descriptors are pollable (see
          <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), then
          any <constant>EPOLLHUP</constant> or <constant>EPOLLERR</constant> event seen on them will result in
-         their automatic removal from the store. Multiple arrays of file descriptors may be sent in separate
-         messages, in which case the arrays are combined. Note that the service manager removes duplicate
-         (pointing to the same object) file descriptors before passing them to the service. When a service is
-         stopped, its file descriptor store is discarded and all file descriptors in it are closed. Use
-         <function>sd_pid_notify_with_fds()</function> to send messages with <literal>FDSTORE=1</literal>, see
-         below. The service manager will set the <varname>$FDSTORE</varname> environment variable for services
-         that have the file descriptor store enabled.</para>
+         their automatic removal from the store.</para>
+ 
+         <para>Multiple sets of file descriptors may be sent in separate messages, in which case the sets are
+         combined. The service manager removes duplicate file descriptors (those pointing to the same object)
+         before passing them to the service.</para>
+ 
+         <para>This functionality should be used to implement services that can restart after an explicit
+         request or a crash without losing state. Application state can either be serialized to a file in
+         <filename>/run/</filename>, or better, stored in a
+         <citerefentry><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+         memory file descriptor. Use <function>sd_pid_notify_with_fds()</function> to send messages with
+         <literal>FDSTORE=1</literal>. It is recommended to combine <varname>FDSTORE=</varname> with
+         <varname>FDNAME=</varname> to make it easier to manage the stored file descriptors.</para>
  
 +        <para>For further information on the file descriptor store see the <ulink
 +        url="https://systemd.io/FILE_DESCRIPTOR_STORE">File Descriptor Store</ulink> overview.</para>
 +
          <xi:include href="version-info.xml" xpointer="v219"/></listitem>
        </varlistentry>