'\" t .\" Title: sd_notify .\" Author: Lennart Poettering .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 10/07/2013 .\" Manual: sd_notify .\" Source: systemd .\" Language: English .\" .TH "SD_NOTIFY" "3" "10/07/2013" "systemd" "sd_notify" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" sd_notify, sd_notifyf \- Notify init system about start\-up completion and other daemon status changes .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'int\ sd_notify('u .BI "int sd_notify(int\ " "unset_environment" ", const\ char\ *" "state" ");" .HP \w'int\ sd_notifyf('u .BI "int sd_notifyf(int\ " "unset_environment" ", const\ char\ *" "format" ", \&.\&.\&.);" .SH "DESCRIPTION" .PP \fBsd_notify()\fR shall be called by a daemon to notify the init system about status 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\&. .PP If the \fIunset_environment\fR parameter is non\-zero \fBsd_notify()\fR will unset the \fI$NOTIFY_SOCKET\fR environment variable before returning (regardless whether the function call itself succeeded or not)\&. Further calls to \fBsd_notify()\fR will then fail, but the variable is no longer inherited by child processes\&. .PP The \fIstate\fR parameter should contain an 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: .PP READY=1 .RS 4 Tells the init system that daemon startup is finished\&. This is only used by systemd if the service 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 only value daemons should send is "READY=1"\&. .RE .PP STATUS=\&.\&.\&. .RS 4 Passes a single\-line status string back to the init system that describes the daemon 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\&.\&.\&." .RE .PP ERRNO=\&.\&.\&. .RS 4 If a daemon fails, the errno\-style error code, formatted as string\&. Example: "ERRNO=2" for ENOENT\&. .RE .PP BUSERROR=\&.\&.\&. .RS 4 If a daemon fails, the D\-Bus error\-style error code\&. Example: "BUSERROR=org\&.freedesktop\&.DBus\&.Error\&.TimedOut" .RE .PP MAINPID=\&.\&.\&. .RS 4 The main pid of the daemon, in case the init system did not fork off the process itself\&. Example: "MAINPID=4711" .RE .PP WATCHDOG=1 .RS 4 Tells systemd to update the watchdog timestamp\&. Services using this feature should do this in regular intervals\&. A watchdog framework can use the timestamps to detect failed services\&. .RE .PP It is recommended to prefix variable names that are not shown in the list above with \fIX_\fR to avoid namespace clashes\&. .PP Note that systemd will accept status data sent from a daemon only if the \fINotifyAccess=\fR option is correctly set in the service definition file\&. See \fBsystemd.service\fR(5) for details\&. .PP \fBsd_notifyf()\fR is similar to \fBsd_notify()\fR but takes a \fBprintf()\fR\-like format string plus arguments\&. .SH "RETURN VALUE" .PP On failure, these calls return a negative errno\-style error code\&. If \fI$NOTIFY_SOCKET\fR 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 don\*(Aqt, it is generally recommended to ignore the return value of this call\&. .SH "NOTES" .PP These functions are provided by the reference implementation of APIs for new\-style daemons and distributed with the systemd package\&. The algorithms they implement are simple, and can easily be reimplemented in daemons if it is important to support this interface without using the reference implementation\&. .PP Internally, these functions send a single datagram with the state string as payload to the AF_UNIX socket referenced in the \fI$NOTIFY_SOCKET\fR environment variable\&. If the first character of \fI$NOTIFY_SOCKET\fR 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\&. .PP For details about the algorithms check the liberally licensed reference implementation sources: \m[blue]\fB\%http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c\fR\m[] resp\&. \m[blue]\fB\%http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h\fR\m[] .PP \fBsd_notify()\fR and \fBsd_notifyf()\fR are implemented in the reference implementation\*(Aqs sd\-daemon\&.c and sd\-daemon\&.h files\&. These interfaces are available as shared library, which can be compiled and linked to with the libsystemd\-daemon \fBpkg-config\fR(1) file\&. Alternatively, applications consuming these APIs may copy the implementation into their source tree\&. For more details about the reference implementation see \fBsd_daemon\fR(7)\&. .PP 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\&. .SH "ENVIRONMENT" .PP \fI$NOTIFY_SOCKET\fR .RS 4 Set by the init system for supervised processes for status and start\-up completion notification\&. This environment variable specifies the socket \fBsd_notify()\fR talks to\&. See above for details\&. .RE .SH "EXAMPLES" .PP \fBExample\ \&1.\ \&Start-up Notification\fR .PP When a daemon finished starting up, it might issue the following call to notify the init system: .sp .if n \{\ .RS 4 .\} .nf sd_notify(0, "READY=1"); .fi .if n \{\ .RE .\} .PP \fBExample\ \&2.\ \&Extended Start-up Notification\fR .PP A daemon could send the following after completing initialization: .sp .if n \{\ .RS 4 .\} .nf sd_notifyf(0, "READY=1\en" "STATUS=Processing requests\&.\&.\&.\en" "MAINPID=%lu", (unsigned long) getpid()); .fi .if n \{\ .RE .\} .PP \fBExample\ \&3.\ \&Error Cause Notification\fR .PP A daemon could send the following shortly before exiting, on failure .sp .if n \{\ .RS 4 .\} .nf sd_notifyf(0, "STATUS=Failed to start up: %s\en" "ERRNO=%i", strerror(errno), errno); .fi .if n \{\ .RE .\} .SH "SEE ALSO" .PP \fBsystemd\fR(1), \fBsd_daemon\fR(7), \fBdaemon\fR(7), \fBsystemd.service\fR(5) .SH "AUTHOR" .PP \fBLennart Poettering\fR <\&lennart@poettering\&.net\&> .RS 4 Developer .RE