Name

sd_notify, sd_notifyf — Notify init system about start-up completion and other daemon status changes

Synopsis

#include "sd-daemon.h"
int fsfuncsd_notify(int unset_environment,
 const char *state);
 
int fsfuncsd_notifyf(int unset_environment,
 const char *format,
 ...);
 

Description

sd_notify() 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.

If the unset_environment parameter is non-zero sd_notify() will unset the $NOTIFY_SOCKET environment variable before returning (regardless 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 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:

READY=1

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".

STATUS=...

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..."

ERRNO=...

If a daemon fails, the errno-style error code, formatted as string. Example: "ERRNO=2" for ENOENT.

BUSERROR=...

If a daemon fails, the D-Bus error-style error code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"

MAINPID=...

The main pid of the daemon, in case the init system did not fork off the process itself. Example: "MAINPID=4711"

It is recommended to prefix variable names that are not shown in the list above with X_ to avoid namespace clashes.

Note that systemd will accept status data sent from a daemon only if the NotifyAccess= option is correctly set in the service definition file. See systemd.service(5) for details.

sd_notifyf() is similar to sd_notifyf() but takes a printf()-like format string plus arguments.