sd_notify, sd_notifyf — Notify service manager about start-up completion and other daemon status changes
#include <systemd/sd-daemon.h>
| int sd_notify( | int unset_environment, | 
| const char *state ); | 
| int sd_notifyf( | int unset_environment, | 
| const char *format, | |
| ... ); | 
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 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:
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".
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..."
If a daemon fails, the errno-style error code, formatted as string. Example: "ERRNO=2" for ENOENT.
If a daemon fails, the D-Bus error-style error code. Example: "BUSERROR=org.freedesktop.DBus.Error.TimedOut"
The main pid of the daemon, in case the init system did not fork off the process itself. Example: "MAINPID=4711"
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.service(5)
                                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 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_notify() but takes a
                printf()-like format string plus
                arguments.
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
                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't, it is generally recommended to ignore the return
                value of this call.
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.
Internally, these functions send a single
                datagram with the state string as payload to the
                AF_UNIX socket referenced in the
                $NOTIFY_SOCKET environment
                variable. If the first character of
                $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 algorithms check the liberally licensed reference implementation sources: http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c and http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h
sd_notify() and
                sd_notifyf() are implemented in
                the reference implementation's
                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
                pkg-config(1)
                file. Alternatively, applications consuming these APIs
                may copy the implementation into their source tree. For
                more details about the reference implementation see
                sd-daemon(3).
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.
$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.
Example 1. Start-up Notification
When a daemon finished starting up, it might issue the following call to notify the init system:
sd_notify(0, "READY=1");
Example 2. Extended Start-up Notification
A daemon could send the following after completing initialization:
sd_notifyf(0, "READY=1\n"
              "STATUS=Processing requests...\n"
              "MAINPID=%lu",
              (unsigned long) getpid());Example 3. Error Cause Notification
A daemon could send the following shortly before exiting, on failure
sd_notifyf(0, "STATUS=Failed to start up: %s\n"
              "ERRNO=%i",
              strerror(errno),
              errno);