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

xmlns:xi="http://www.w3.org/2001/XInclude">

<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 service 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> 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.</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 of

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

<variablelist>

<varlistentry>

<term>READY=1</term>

<listitem><para>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

<literal>READY=1</literal>

(i.e. <literal>READY=0</literal> is

not defined).</para></listitem>

</varlistentry>

<varlistentry>

<term>RELOADING=1</term>

<listitem><para>Tells the service manager

that the service is reloading its

configuration. This is useful to allow

the service manager to track the service's

internal state, and present it to the

user. Note that a service that sends

this notification must also send a

<literal>READY=1</literal>

notification when it completed

reloading its

configuration.</para></listitem>

</varlistentry>

<varlistentry>

<term>STOPPING=1</term>

<listitem><para>Tells the service manager

that the service is beginning its

shutdown. This is useful to allow the

service manager to track the service's

internal state, and present it to the

user.</para></listitem>

</varlistentry>

<varlistentry>

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

<listitem><para>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:

<literal>STATUS=Completed 66% of file

system

check...</literal></para></listitem>

</varlistentry>

<varlistentry>

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

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

errno-style error code, formatted as

string. Example: <literal>ERRNO=2</literal> for

ENOENT.</para></listitem>

</varlistentry>

<varlistentry>

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

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

D-Bus error-style error code. Example:

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

</varlistentry>

<varlistentry>

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

<listitem><para>The main pid of the

service, in case the service manager did

not fork off the process

itself. Example:

<literal>MAINPID=4711</literal></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 information how to enable this

functionality and

<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>

for the details of how the service can

check if the the watchdog is enabled.

</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 service 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

do not, it is generally recommended to ignore the return

value of this call.</para>

</refsect1>

<refsect1>

<title>Notes</title>

<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>

<para>Internally, these functions send a single

datagram with the state string as payload to the

<constant>AF_UNIX</constant> socket referenced in the

<varname>$NOTIFY_SOCKET</varname> environment

variable. If the first character of

<varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is

understood as Linux abstract namespace socket. The

datagram is accompanied by the process credentials of

the sending service, using SCM_CREDENTIALS.</para>

</refsect1>

<refsect1>

<title>Environment</title>

<variablelist class='environment-variables'>

<varlistentry>

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

<listitem><para>Set by the service manager

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 service finished starting up, it

might issue the following call to notify

the service manager:</para>

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

</example>

<example>

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

<para>A service 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 service 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>,

<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>