X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_notify.xml;h=856b1bcbc2fcfbfc711c5913d10d4d3b840b51ec;hp=41c3f3fa78f5b6506f1a7e9d757fac454d884479;hb=39d1301db9c8d38c3454744456127ad8322caae2;hpb=1532f28b7cf3e6e02e74691450b2b5379be6b805 diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 41c3f3fa7..856b1bcbc 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,4 +1,4 @@ - + @@ -66,7 +66,7 @@ int sd_notifyf int unset_environment const char *format - ... + … @@ -81,7 +81,7 @@ pid_t pid int unset_environment const char *format - ... + … @@ -100,7 +100,7 @@ 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 + environment-block-like string. Most importantly, it can be used for start-up completion notification. If the unset_environment parameter is @@ -152,19 +152,19 @@ - STATUS=... + STATUS=… Passes a single-line UTF-8 status string back to the service manager that describes the service state. This is free-form and can be used for various purposes: general state feedback, fsck-like programs could pass completion - percentages and failing programs could pass a human readable + 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. @@ -194,7 +194,7 @@ watchdog timestamp. This is the keep-alive ping that services need to issue in regular intervals if WatchdogSec= is enabled for it. See - elogind.service5 + systemd.service5 for information how to enable this functionality and sd_watchdog_enabled3 for the details of how the service can check whether the @@ -205,28 +205,54 @@ 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 - elogind.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=… + + When used in combination with + FDSTORE=1, specifies a name for the + submitted file descriptors. 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 any ASCII character, but must not contain control + characters or :. It may not be longer than + 255 characters. If a submitted name does not follow these + restrictions, it is ignored. + + + + WATCHDOG_USEC=… + + Reset watchdog_usec value during runtime. + Notice that this is not available when using sd_event_set_watchdog() + or sd_watchdog_enabled(). + Example : WATCHDOG_USEC=20000000 @@ -238,9 +264,18 @@ Note that elogind will accept status data sent from a service only if the NotifyAccess= option is correctly set in the service definition file. See - elogind.service5 + 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 @@ -253,7 +288,7 @@ 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 + 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(). @@ -276,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). @@ -290,7 +326,7 @@ - Internally, these functions send a single datagram with the + These functions send a single datagram with the state string as payload to the AF_UNIX socket referenced in the $NOTIFY_SOCKET environment variable. If the first character of @@ -335,7 +371,7 @@ initialization: sd_notifyf(0, "READY=1\n" - "STATUS=Processing requests...\n" + "STATUS=Processing requests…\n" "MAINPID=%lu", (unsigned long) getpid()); @@ -356,20 +392,22 @@ 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: + losing state, use FDSTORE=1: - sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1); + sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1); See Also - elogind1, + systemd1, sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, daemon7, - elogind.service5, - sd_watchdog_enabled3 + systemd.service5