X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_notify.xml;h=f2710b6ab3d07caa015e0efd3701ef7a18c64069;hp=b7c33da63af35f44b8dc8b504a3f1720543ae670;hb=8036e4d0b9ef0990597196155fe6fc6329a6a881;hpb=cc98b3025eeb89addb76a27390cb2baca4eab8b9 diff --git a/man/sd_notify.xml b/man/sd_notify.xml index b7c33da63..f2710b6ab 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -1,428 +1,405 @@ - + + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - sd_notify - systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - - - - - sd_notify - 3 - - - - 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 - - - - - #include <systemd/sd-daemon.h> - - - int sd_notify - int unset_environment - const char *state - - - - int sd_notifyf - int unset_environment - 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 - - - - - - Description - 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 start-up - completion notification. - - If the unset_environment - parameter is non-zero, sd_notify() - will unset the $NOTIFY_SOCKET - environment variable before returning (regardless of - whether the function call itself succeeded or - not). Further calls to - sd_notify() will then fail, but - the variable is no longer inherited by child - processes. - - The state parameter - should contain a newline-separated list of variable - assignments, similar in style to an environment - block. A trailing newline is implied if none is - specified. The string may contain any kind of variable - assignments, but the following shall be considered - well-known: - - - - READY=1 - - Tells the service - manager that service startup is - finished. This is only used by systemd - if the service definition file has - Type=notify set. Since there is little - value in signaling non-readiness, the - only value services should send is - READY=1 - (i.e. READY=0 is - not defined). - - - - RELOADING=1 - - Tells the service manager - that the service is reloading its - configuration. This is useful to allow - the service manager to track the service's - internal state, and present it to the - user. Note that a service that sends - this notification must also send a - READY=1 - notification when it completed - reloading its - configuration. - - - - STOPPING=1 - - Tells the service manager - that the service is beginning its - shutdown. This is useful to allow the - service manager to track the service's - internal state, and present it to the - user. - - - - 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 error message. Example: - STATUS=Completed 66% of file - system - check... - - - - ERRNO=... - - If a service fails, the - errno-style error code, formatted as - string. Example: ERRNO=2 for - ENOENT. - - - - BUSERROR=... - - If a service fails, the - D-Bus error-style error code. Example: - BUSERROR=org.freedesktop.DBus.Error.TimedOut - - - - MAINPID=... - - The main process ID (PID) of the - service, in case the service manager did - not fork off the process - itself. Example: - MAINPID=4711 - - - - WATCHDOG=1 - - 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 information how to enable this - functionality and - sd_watchdog_enabled3 - 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 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. - - - - - It is recommended to prefix variable names that - are not listed above with X_ to - avoid namespace clashes. - - Note that systemd will accept status data sent - from a service only if the - NotifyAccess= option is correctly - set in the service definition file. See - systemd.service5 - for details. - - sd_notifyf() is similar to - 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. - - - - 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. - - - - Notes - - - - Internally, 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 - $NOTIFY_SOCKET is @, the string is - understood as Linux abstract namespace socket. The - datagram is accompanied by the process credentials of - the sending service, using SCM_CREDENTIALS. - - - - Environment - - - - $NOTIFY_SOCKET - - Set by the service manager - for supervised processes for status - and start-up completion - notification. This environment variable - specifies the socket - sd_notify() talks - to. See above for details. - - - - - - Examples - - - Start-up Notification - - When a service finished starting up, it - might issue the following call to notify - the service manager: - - sd_notify(0, "READY=1"); - - - - Extended Start-up Notification - - A service could send the following after - completing initialization: - - sd_notifyf(0, "READY=1\n" - "STATUS=Processing requests...\n" - "MAINPID=%lu", - (unsigned long) getpid()); - - - - Error Cause Notification - - 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); - - - - - See Also - - systemd1, - sd-daemon3, - daemon7, - systemd.service5, - sd_watchdog_enabled3 - - + xmlns:xi="http://www.w3.org/2001/XInclude"> + + + sd_notify + elogind + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_notify + 3 + + + + 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 + + + + + #include <elogind/sd-daemon.h> + + + int sd_notify + int unset_environment + const char *state + + + + int sd_notifyf + int unset_environment + 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 + + + + + + Description + 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 + start-up completion notification. + + If the unset_environment parameter is + non-zero, sd_notify() will unset the + $NOTIFY_SOCKET environment variable before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_notify() will then fail, but the variable + is no longer inherited by child processes. + + The state parameter should contain a + newline-separated list of variable assignments, similar in style + to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known: + + + + READY=1 + + Tells the service manager that service startup + is finished. This is only used by elogind if the service + definition file has Type=notify set. Since there is little + value in signaling non-readiness, the only value services + should send is READY=1 (i.e. + READY=0 is not defined). + + + + RELOADING=1 + + Tells the service manager that the service is + reloading its configuration. This is useful to allow the + service manager to track the service's internal state, and + present it to the user. Note that a service that sends this + notification must also send a READY=1 + notification when it completed reloading its + configuration. + + + + STOPPING=1 + + Tells the service manager that the service is + beginning its shutdown. This is useful to allow the service + manager to track the service's internal state, and present it + to the user. + + + + 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 + error message. Example: STATUS=Completed 66% of file + system check... + + + + ERRNO=... + + If a service fails, the errno-style error + code, formatted as string. Example: ERRNO=2 + for ENOENT. + + + + BUSERROR=... + + If a service fails, the D-Bus error-style + error code. Example: + BUSERROR=org.freedesktop.DBus.Error.TimedOut + + + + MAINPID=... + + The main process ID (PID) of the service, in + case the service manager did not fork off the process itself. + Example: MAINPID=4711 + + + + WATCHDOG=1 + + 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 information how to enable this functionality and + sd_watchdog_enabled3 + for the details of how the service can check whether 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 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. + + + + 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 + + + + + It is recommended to prefix variable names that are not + listed above with X_ to avoid namespace + clashes. + + 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 + systemd.service5 + for details. + + sd_notifyf() is similar to + 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. + + + + 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. + + + + Notes + + + + 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 + $NOTIFY_SOCKET is @, the + string is understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of the sending + service, using SCM_CREDENTIALS. + + + + Environment + + + + $NOTIFY_SOCKET + + Set by the service manager for supervised + processes for status and start-up completion notification. + This environment variable specifies the socket + sd_notify() talks to. See above for + details. + + + + + + Examples + + + Start-up Notification + + When a service finished starting up, it might issue the + following call to notify the service manager: + + sd_notify(0, "READY=1"); + + + + Extended Start-up Notification + + A service could send the following after completing + initialization: + + sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid()); + + + + Error Cause Notification + + 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\nFDNAME=foobar", &fd, 1); + + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + sd_listen_fds_with_names3, + sd_watchdog_enabled3, + daemon7, + systemd.service5 + +