X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_notify.xml;h=856b1bcbc2fcfbfc711c5913d10d4d3b840b51ec;hb=39d1301db9c8d38c3454744456127ad8322caae2;hp=03efe0193a7501bfd3bb4863feaa1903bc335156;hpb=35eec258c4523c92fe985d764198b266ebc3881a;p=elogind.git
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 03efe0193..856b1bcbc 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -66,7 +66,7 @@
int sd_notifyfint unset_environmentconst char *format
- ...
+ â¦
@@ -81,7 +81,7 @@
pid_t pidint unset_environmentconst char *format
- ...
+ â¦
@@ -152,7 +152,7 @@
- STATUS=...
+ STATUS=â¦Passes a single-line UTF-8 status string back
to the service manager that describes the service state. This
@@ -160,11 +160,11 @@
state feedback, fsck-like programs could pass completion
percentages and failing programs could pass a human-readable
error message. Example: STATUS=Completed 66% of file
- system check...
+ system checkâ¦
- ERRNO=...
+ ERRNO=â¦If a service fails, the errno-style error
code, formatted as string. Example: ERRNO=2
@@ -172,7 +172,7 @@
- BUSERROR=...
+ BUSERROR=â¦If a service fails, the D-Bus error-style
error code. Example:
@@ -180,7 +180,7 @@
- MAINPID=...
+ MAINPID=â¦The main process ID (PID) of the service, in
case the service manager did not fork off the process itself.
@@ -205,32 +205,28 @@
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 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
- for details. 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.
- FDNAME=...
+ FDNAME=â¦When used in combination with
FDSTORE=1, specifies a name for the
@@ -251,7 +247,7 @@
- WATCHDOG_USEC=...
+ WATCHDOG_USEC=â¦Reset watchdog_usec value during runtime.
Notice that this is not available when using sd_event_set_watchdog()
@@ -271,6 +267,15 @@
systemd.service5
for details.
+ Note that sd_notify() notifications may be attributed to units correctly only if either
+ the sending process is still around at the time PID 1 processes the message, or if the sending process is
+ explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
+ off the process, i.e. on all processes that match NotifyAccess= or
+ NotifyAccess=. Conversely, if an auxiliary process of the unit sends an
+ sd_notify() message and immediately exits, the service manager might not be able to properly
+ attribute the message to the unit, and thus will ignore it, even if
+ NotifyAccess= is set for it.
+
sd_notifyf() is similar to
sd_notify() but takes a
printf()-like format string plus
@@ -306,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).
@@ -365,7 +371,7 @@
initialization:sd_notifyf(0, "READY=1\n"
- "STATUS=Processing requests...\n"
+ "STATUS=Processing requestsâ¦\n"
"MAINPID=%lu",
(unsigned long) getpid());