X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_notify.xml;h=7d9689039727a4214b6908747cbfc15211f367dd;hp=140e795979083150192cc88a5b9b9b71826270e0;hb=6577c7cea72f19185ad999c223bcf663c010dc6f;hpb=f9378423b9758861850748aeb49ae0d3300e56e6 diff --git a/man/sd_notify.xml b/man/sd_notify.xml index 140e79597..7d9689039 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -8,16 +8,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -45,12 +45,12 @@ sd_notify sd_notifyf - Notify init system about start-up completion and other daemon status changes + Notify service manager about start-up completion and other daemon status changes - #include "sd-daemon.h" + #include <systemd/sd-daemon.h> int sd_notify @@ -87,7 +87,7 @@ processes. The state parameter - should contain an newline-seperated list of variable + 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 @@ -104,7 +104,7 @@ definition file has Type=notify set. The passed argument is a boolean "1" or "0". Since there is little - value in signalling non-readiness the + value in signaling non-readiness, the only value daemons should send is "READY=1". @@ -115,7 +115,7 @@ Passes a single-line status string back to the init system that describes the daemon state. This - is free-from and can be used for + is free-form and can be used for various purposes: general state feedback, fsck-like programs could pass completion percentages and @@ -151,9 +151,28 @@ itself. Example: "MAINPID=4711" + + + WATCHDOG=1 + + Tells systemd 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_USEC= + environment variable has been set for + the service process, in every half the + time interval that is specified in the + variable. + - It is recommened to prefix variable names that + It is recommended to prefix variable names that are not shown in the list above with X_ to avoid namespace clashes. @@ -166,7 +185,7 @@ for details. sd_notifyf() is similar to - sd_notifyf() but takes a + sd_notify() but takes a printf()-like format string plus arguments. @@ -177,11 +196,11 @@ 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 + 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 + positive return value. In order to support both, init systems that implement this scheme and those which - don't it is generally recommended to ignore the return + don't, it is generally recommended to ignore the return value of this call. @@ -198,33 +217,55 @@ Internally, these functions send a single datagram with the state string as payload to the - AF_UNIX socket referenced in the + AF_UNIX socket referenced in the $NOTIFY_SOCKET environment variable. If the first character of - $NOTIFY_SOCKET is @ the string is + $NOTIFY_SOCKET is @ the string is understood as Linux abstract namespace socket. The datagram is accompanied by the process credentials of the sending daemon, using SCM_CREDENTIALS. - For details about the algorithm check the + For details about the algorithms check the liberally licensed reference implementation sources: - - resp. + + and sd_notify() and sd_notifyf() are implemented in - the reference implementation's drop-in + the reference implementation's sd-daemon.c and - sd-daemon.h files. It is - recommended that applications consuming these APIs - copy the implementation into their source tree. For + sd-daemon.h files. These + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-daemon pkg-config1 + file. Alternatively, applications consuming these APIs + may copy the implementation into their source tree. For more details about the reference implementation see - sd_daemon7 + sd-daemon3. + + If the reference implementation is used as + drop-in files and -DDISABLE_SYSTEMD is set during + compilation these functions will always return 0 and + otherwise become a NOP. + - If -DDISABLE_SYSTEMD is set during compilation - this function will always return 0 and otherwise - become a NOP. + + Environment + + + + $NOTIFY_SOCKET + + Set by the init system + for supervised processes for status + and start-up completion + notification. This environment variable + specifies the socket + sd_notify() talks + to. See above for details. + + @@ -234,7 +275,7 @@ Start-up Notification When a daemon finished starting up, it - might issue the following call call to notify + might issue the following call to notify the init system: sd_notify(0, "READY=1"); @@ -267,9 +308,9 @@ See Also - sd_daemon7, + systemd1, + sd-daemon3, daemon7, - systemd8, systemd.service5