systemd/man/sd_notify.3

'\" t
.TH "SD_NOTIFY" "3" "" "systemd 219" "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, sd_pid_notify, sd_pid_notifyf, sd_pid_notify_with_fds \- Notify service manager about start\-up completion and other service 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" ", \&.\&.\&.);"
.HP \w'int\ sd_pid_notify('u
.BI "int sd_pid_notify(pid_t\ " "pid" ", int\ " "unset_environment" ", const\ char\ *" "state" ");"
.HP \w'int\ sd_pid_notifyf('u
.BI "int sd_pid_notifyf(pid_t\ " "pid" ", int\ " "unset_environment" ", const\ char\ *" "format" ", \&.\&.\&.);"
.HP \w'int\ sd_pid_notify_with_fds('u
.BI "int sd_pid_notify_with_fds(pid_t\ " "pid" ", int\ " "unset_environment" ", const\ char\ *" "state" ", const\ int\ *" "fds" ", unsigned\ " "n_fds" ");"
.SH "DESCRIPTION"
.PP
\fBsd_notify()\fR
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\&.
.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 of 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 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)\&.
.RE
.PP
RELOADING=1
.RS 4
Tells the service manager that the service is reloading its configuration\&. This is useful to allow the service manager to track the service\*(Aqs 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\&.
.RE
.PP
STOPPING=1
.RS 4
Tells the service manager that the service is beginning its shutdown\&. This is useful to allow the service manager to track the service\*(Aqs internal state, and present it to the user\&.
.RE
.PP
STATUS=\&.\&.\&.
.RS 4
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\&.\&.\&."
.RE
.PP
ERRNO=\&.\&.\&.
.RS 4
If a service fails, the errno\-style error code, formatted as string\&. Example:
"ERRNO=2"
for ENOENT\&.
.RE
.PP
BUSERROR=\&.\&.\&.
.RS 4
If a service fails, the D\-Bus error\-style error code\&. Example:
"BUSERROR=org\&.freedesktop\&.DBus\&.Error\&.TimedOut"
.RE
.PP
MAINPID=\&.\&.\&.
.RS 4
The main process ID (PID) of the service, in case the service manager did not fork off the process itself\&. Example:
"MAINPID=4711"
.RE
.PP
WATCHDOG=1
.RS 4
Tells the service manager 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 information how to enable this functionality and
\fBsd_watchdog_enabled\fR(3)
for the details of how the service can check if the the watchdog is enabled\&.
.RE
.PP
FDSTORE=1
.RS 4
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
\fBsd_listen_fds\fR(3))\&. 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
\fIFileDescriptorStoreMax=\fR
is set to non\-zero for it (defaults to zero)\&. See
\fBsystemd.service\fR(5)
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
\fBsd_pid_notify_with_fds()\fR
to send messages with
"FDSTORE=1", see below\&.
.RE
.PP
It is recommended to prefix variable names that are not listed above with
\fIX_\fR
to avoid namespace clashes\&.
.PP
Note that systemd will accept status data sent from a service 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\&.
.PP
\fBsd_pid_notify()\fR
and
\fBsd_pid_notifyf()\fR
are similar to
\fBsd_notify()\fR
and
\fBsd_notifyf()\fR
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
\fBsd_notify()\fR
and
\fBsd_notifyf()\fR\&.
.PP
\fBsd_pid_notify_with_fds()\fR
is similar to
\fBsd_pid_notify()\fR
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
\fBsd_pid_notify()\fR, 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\&.
.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 APIs are implemented as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.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 service, using SCM_CREDENTIALS\&.
.SH "ENVIRONMENT"
.PP
\fI$NOTIFY_SOCKET\fR
.RS 4
Set by the service manager 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 service finished starting up, it might issue the following call to notify the service manager:
.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 service 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 service 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
.\}
.PP
\fBExample\ \&4.\ \&Store a File Descriptor in the Service Manager\fR
.PP
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":
.sp
.if n \{\
.RS 4
.\}
.nf
sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-daemon\fR(3),
\fBdaemon\fR(7),
\fBsystemd.service\fR(5),
\fBsd_watchdog_enabled\fR(3)