path: root/man/sd_notify.3

'\" t
.TH "SD_NOTIFY" "3" "" "systemd 208" "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 service manager about start\-up completion and other daemon status changes
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-daemon\&.h>
.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 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:
.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 signaling 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\&. This is the keep\-alive ping that services need to issue in regular intervals if
\fIWatchdogSec=\fR
is enabled for it\&. See
\fBsystemd.service\fR(5)
for details\&. It is recommended to send this message if the
\fIWATCHDOG_USEC=\fR
environment variable has been set for the service process, in every half the time interval that is specified in the variable\&.
.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 do not, 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
\fBAF_UNIX\fR
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/libsystemd-daemon/sd-daemon.c\fR\m[]
and
\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
\fBlibsystemd\-daemon\fR\ \&\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(3)\&.
.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(3),
\fBdaemon\fR(7),
\fBsystemd.service\fR(5)