diff --git a/man/sd_notify.xml b/man/sd_notify.xml index a0f28703c4..a6a9a9bed8 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -98,13 +98,13 @@ Description sd_notify() may be called by a service to notify the service manager about - state changes. It can be used to send arbitrary information, encoded in an environment-block-like - string. Most importantly, it can be used for start-up completion notification. + state changes. It can be used to send arbitrary information, encoded in an environment-block-like string. + Most importantly, it can be used for start-up or reload completion notifications. If the unset_environment parameter is non-zero, sd_notify() will unset the $NOTIFY_SOCKET environment variable before returning (regardless of whether the function call itself succeeded or not). Further calls to - sd_notify() will then fail, but the variable is no longer inherited by child + sd_notify() will then fail, and the variable is no longer inherited by child processes. The state parameter should contain a newline-separated list of variable @@ -336,29 +336,40 @@ FDSTORE=1 - 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 + 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 sd_listen_fds3. - 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 - /run/, or better, stored in a - memfd_create2 - 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 FileDescriptorStorePreserve=, see + systemd.service5. + + + The service manager will accept messages for a service only if its FileDescriptorStoreMax= setting is non-zero (defaults to zero, see - systemd.service5). If - FDPOLL=0 is not set and the file descriptors sent are pollable (see + systemd.service5). + The service manager will set the $FDSTORE environment variable for services that + have the file descriptor store enabled, see + systemd.exec5. + + + If FDPOLL=0 is not set and the file descriptors are pollable (see epoll_ctl2), then any EPOLLHUP or EPOLLERR 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 - sd_pid_notify_with_fds() to send messages with FDSTORE=1, see - below. The service manager will set the $FDSTORE environment variable for services - that have the file descriptor store enabled. + their automatic removal from the store. + + 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. + + 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 + /run/, or better, stored in a + memfd_create2 + memory file descriptor. Use sd_pid_notify_with_fds() to send messages with + FDSTORE=1. It is recommended to combine FDSTORE= with + FDNAME= to make it easier to manage the stored file descriptors. @@ -380,14 +391,16 @@ submitted file descriptors. When used with FDSTOREREMOVE=1, specifies the name for the file descriptors to remove. This name is passed to the service during activation, and may be queried using - sd_listen_fds_with_names3. File - descriptors submitted without this field set, will implicitly get the name stored - assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be - assigned to all of them. In order to assign different names to submitted file descriptors, submit - them in separate invocations of sd_pid_notify_with_fds(). The name may consist - of arbitrary ASCII characters except control characters or :. It may not be longer - than 255 characters. If a submitted name does not follow these restrictions, it is - ignored. + sd_listen_fds_with_names3. + File descriptors submitted without this field will be called stored. + + The name may consist of arbitrary ASCII characters except control characters or + :. It may not be longer than 255 characters. If a submitted name does not follow + these restrictions, it is ignored. + + Note that if multiple file descriptors are submitted in a single message, the specified name + will be used for all of them. In order to assign different names to submitted file descriptors, + submit them in separate messages. diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 18928a4e85..1521dfd763 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -3998,12 +3998,12 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX $FDSTORE - If the file descriptor store is enabled for a service - (i.e. FileDescriptorStoreMax= is set to a non-zero value, see + The maximum number of file descriptors that may be stored in the manager for the + service. This variable is set when the file descriptor store is enabled for the service, i.e. + FileDescriptorStoreMax= is set to a non-zero value (see systemd.service5 - for details), this environment variable will be set to the maximum number of permitted entries, as - per the setting. Applications may check this environment variable before sending file descriptors - to the service manager via sd_pid_notify_with_fds() (see + for details). Applications may check this environment variable before sending file descriptors to + the service manager via sd_pid_notify_with_fds() (see sd_notify3 for details).