X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_notify.xml;fp=man%2Fsd_notify.xml;h=856b1bcbc2fcfbfc711c5913d10d4d3b840b51ec;hp=f3f3269769bdee77fd56f301a63d81444c013df0;hb=39d1301db9c8d38c3454744456127ad8322caae2;hpb=0cd0e2ee1908a1432b06e637168f7fc8531643ec
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index f3f326976..856b1bcbc 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -205,25 +205,24 @@
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 be passed again using the usual file descriptor passing logic on the next
- invocation of the service, see
- sd_listen_fds3.
- This is useful for implementing service restart schemes where services serialize
- their state to /run, push their file descriptors to the
- system manager, and are then restarted, retrieving their state again via socket
- passing and /run. Note that the service manager will accept
- messages for a service only if FileDescriptorStoreMax= is set
- to non-zero for it (defaults to zero, see
- systemd.service5).
- File descriptors must be pollable, see
- epoll_ctl2.
- 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
- file descriptors before passing them to the service. Use
- sd_pid_notify_with_fds() to send messages with
- FDSTORE=1, see below.
+ 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, 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
+ FileDescriptorStoreMax= setting is non-zero (defaults to zero, see
+ systemd.service5). If file
+ descriptors sent 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. Use sd_pid_notify_with_fds()
+ to send messages with FDSTORE=1, see below.
@@ -312,13 +311,14 @@
Return Value
- On failure, these calls return a negative errno-style error
- code. If $NOTIFY_SOCKET was not set and hence
- no status data could be sent, 0 is returned. If the status was
- sent, these functions return with a positive return value. In
- order to support both, init systems that implement this scheme and
- those which do not, it is generally recommended to ignore the
- return value of this call.
+ On failure, these calls return a negative errno-style error code. If $NOTIFY_SOCKET was
+ not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
+ positive value. In order to support both service managers that implement this scheme and those which do not, it is
+ generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
+ the notification message was enqueued properly, it does not reflect whether the message could be processed
+ successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
+ FDSTORE=1 but the service is not actually configured to permit storing of file descriptors (see
+ above).