X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_notify.xml;h=2bf3383c0db38793eccfcbecdbf86796b06603dc;hb=975a900782528b57deafadc10457c7ffab0b9791;hp=fbb882dfd2c0e0c0f177232b6e293c361fa88ee4;hpb=308d72dc1e2106f94ae637e2ea510e8d466d2af1;p=elogind.git
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index fbb882dfd..2bf3383c0 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -46,6 +46,9 @@
sd_notify
sd_notifyf
+ sd_pid_notify
+ sd_pid_notifyf
+ sd_pid_notify_with_fds
Notify service manager about start-up completion and other service status changes
@@ -65,6 +68,30 @@
const char *format
...
+
+
+ int sd_pid_notify
+ pid_t pid
+ int unset_environment
+ const char *state
+
+
+
+ int sd_pid_notifyf
+ pid_t pid
+ int unset_environment
+ const char *format
+ ...
+
+
+
+ int sd_pid_notify_with_fds
+ pid_t pid
+ int unset_environment
+ const char *state
+ const int *fds
+ unsigned n_fds
+
@@ -175,7 +202,7 @@
MAINPID=...
- The main pid of the
+ The main process ID (PID) of the
service, in case the service manager did
not fork off the process
itself. Example:
@@ -185,31 +212,67 @@
WATCHDOG=1
- Tells systemd to
+ Tells the service manager to
update the watchdog timestamp. This is
the keep-alive ping that services need
to issue in regular intervals if
WatchdogSec= is
enabled for it. See
systemd.service5
- for details. It is recommended to send
- this message if the
- $WATCHDOG_PID
- environment variable has been set to
- the PID of the service process, in
- every half the time interval that is
- specified in the
- $WATCHDOG_USEC
- environment variable. See
+ for information how to enable this
+ functionality and
sd_watchdog_enabled3
- for details.
+ for the details of how the service can
+ check if the the watchdog is enabled.
+
+
+
+
+
+ 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 seperate
+ 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.
+
It is recommended to prefix variable names that
- are not shown in the list above with
- X_ to avoid namespace
- clashes.
+ are not listed above with X_ to
+ avoid namespace clashes.
Note that systemd will accept status data sent
from a service only if the
@@ -222,6 +285,36 @@
sd_notify() but takes a
printf()-like format string plus
arguments.
+
+ sd_pid_notify() and
+ sd_pid_notifyf() are similar to
+ sd_notify() and
+ sd_notifyf() but take a process
+ ID (PID) to use as originating PID for the message as
+ first argument. This is useful to send notification
+ messages on behalf of other processes, provided the
+ appropriate privileges are available. If the PID
+ argument is specified as 0 the process ID of the
+ calling process is used, in which case the calls are
+ fully equivalent to sd_notify()
+ and sd_notifyf().
+
+ sd_pid_notify_with_fds() is
+ similar to sd_pid_notify() but
+ takes an additional array of file descriptors. These
+ file descriptors are sent along the notification
+ message to the service manager. This is particularly
+ useful for sending FDSTORE=1
+ messages, as described above. The additional arguments
+ are a pointer to the file descriptor array plus the
+ number of file descriptors in the array. If the number
+ of file descriptors is passed as 0, the call is fully
+ equivalent to sd_pid_notify(),
+ i.e. no file descriptors are passed. Note that sending
+ file descriptors to the service manager on messages
+ that do not expect them (i.e. without
+ FDSTORE=1) they are immediately
+ closed on reception.
@@ -300,13 +393,25 @@
Error Cause Notification
- A service could send the following shortly before exiting, on failure
+ A service could send the following shortly before exiting, on failure:
sd_notifyf(0, "STATUS=Failed to start up: %s\n"
"ERRNO=%i",
strerror(errno),
errno);
+
+
+ Store a File Descriptor in the Service Manager
+
+ To store an open file descriptor in the
+ service manager, in order to continue
+ operation after a service restart without
+ losing state use
+ FDSTORE=1:
+
+ sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);
+