<?xml version='1.0'?> <!--*-nxml-*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sd_notify">

<refentryinfo>

<title>sd_notify</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>sd_notify</refentrytitle>

<manvolnum>3</manvolnum>

</refmeta>

<refnamediv>

<refname>sd_notify</refname>

<refname>sd_notifyf</refname>

<refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>

<funcprototype>

<funcdef>int <function>sd_notify</function></funcdef>

<paramdef>int <parameter>unset_environment</parameter></paramdef>

<paramdef>const char *<parameter>state</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_notifyf</function></funcdef>

<paramdef>int <parameter>unset_environment</parameter></paramdef>

<paramdef>const char *<parameter>format</parameter></paramdef>

<paramdef>...</paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

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

<para>If the <parameter>unset_environment</parameter>

parameter is non-zero <function>sd_notify()</function>

will unset the <varname>$NOTIFY_SOCKET</varname>

environment variable before returning (regardless

whether the function call itself succeeded or

not). Further calls to

<function>sd_notify()</function> will then fail, but

the variable is no longer inherited by child

processes.</para>

<para>The <parameter>state</parameter> 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:</para>

<variablelist>

<varlistentry>

<term>READY=1</term>

<listitem><para>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".</para></listitem>

</varlistentry>

<varlistentry>

<term>STATUS=...</term>

<listitem><para>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..."</para></listitem>

</varlistentry>

<varlistentry>

<term>ERRNO=...</term>

<listitem><para>If a daemon fails, the

errno-style error code, formatted as

string. Example: "ERRNO=2" for

ENOENT.</para></listitem>

</varlistentry>

<varlistentry>

<term>BUSERROR=...</term>

<listitem><para>If a daemon fails, the

D-Bus error-style error code. Example:

"BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>

</varlistentry>

<varlistentry>

<term>MAINPID=...</term>

<listitem><para>The main pid of the

daemon, in case the init system did

not fork off the process

itself. Example:

"MAINPID=4711"</para></listitem>

</varlistentry>

<varlistentry>

<term>WATCHDOG=1</term>

<listitem><para>Tells systemd to

update the watchdog timestamp. This is

the keep-alive ping that services need

to issue in regular intervals if

<varname>WatchdogSec=</varname> is

enabled for it. See

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for details. It is recommended to send

this message if the

<varname>WATCHDOG_USEC=</varname>

environment variable has been set for

the service process, in every half the

time interval that is specified in the

variable.</para></listitem>

</varlistentry>

</variablelist>

<para>It is recommended to prefix variable names that

are not shown in the list above with

<varname>X_</varname> to avoid namespace

clashes.</para>

<para>Note that systemd will accept status data sent

from a daemon only if the

<varname>NotifyAccess=</varname> option is correctly

set in the service definition file. See

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for details.</para>

<para><function>sd_notifyf()</function> is similar to

<function>sd_notify()</function> but takes a

<function>printf()</function>-like format string plus

arguments.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On failure, these calls return a negative

errno-style error code. If

<varname>$NOTIFY_SOCKET</varname> 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.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>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.</para>

<para>Internally, these functions send a single

datagram with the state string as payload to the

AF_UNIX socket referenced in the

<varname>$NOTIFY_SOCKET</varname> environment

variable. If the first character of

<varname>$NOTIFY_SOCKET</varname> 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.</para>

<para>For details about the algorithms check the

liberally licensed reference implementation sources:

<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>

resp. <ulink

url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>

<para><function>sd_notify()</function> and

<function>sd_notifyf()</function> are implemented in

the reference implementation's

<filename>sd-daemon.c</filename> and

<filename>sd-daemon.h</filename> files. These

interfaces are available as shared library, which can

be compiled and linked to with the

<literal>libsystemd-daemon</literal>

<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

file. Alternatively, applications consuming these APIs

may copy the implementation into their source tree. For

more details about the reference implementation see

<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

<para>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.</para>

</refsect1>

<refsect1>

<title>Environment</title>

<variablelist>

<varlistentry>

<term><varname>$NOTIFY_SOCKET</varname></term>

<listitem><para>Set by the init system

for supervised processes for status

and start-up completion

notification. This environment variable

specifies the socket

<function>sd_notify()</function> talks

to. See above for details.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Examples</title>

<example>

<title>Start-up Notification</title>

<para>When a daemon finished starting up, it

might issue the following call to notify

the init system:</para>

<programlisting>sd_notify(0, "READY=1");</programlisting>

</example>

<example>

<title>Extended Start-up Notification</title>

<para>A daemon could send the following after

completing initialization:</para>

<programlisting>sd_notifyf(0, "READY=1\n"

"STATUS=Processing requests...\n"

"MAINPID=%lu",

(unsigned long) getpid());</programlisting>

</example>

<example>

<title>Error Cause Notification</title>

<para>A daemon could send the following shortly before exiting, on failure</para>

<programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"

"ERRNO=%i",

strerror(errno),

errno);</programlisting>

</example>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>