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_notifyf int unset_environment const char *format - ... + … @@ -81,7 +81,7 @@ pid_t pid int unset_environment const 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());