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

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

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

a945f35eff8b6a88009ce73de6d4c862ce58de3cslive

3f08db06526d6901aa08c110b5bc7dde6bc39905nd

b686b6a420bde7f78c416b90be11db94cb789979nd<refentry id="sd_notify">

b686b6a420bde7f78c416b90be11db94cb789979nd

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <refentryinfo>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <title>sd_notify</title>

0066eddda7203f6345b56f77d146a759298dc635gryzor <productname>systemd</productname>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd

f3ec420152ca921e4c1ce77782f51b53f659018dnd <authorgroup>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <author>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <contrib>Developer</contrib>

b686b6a420bde7f78c416b90be11db94cb789979nd <firstname>Lennart</firstname>

b686b6a420bde7f78c416b90be11db94cb789979nd <surname>Poettering</surname>

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

b686b6a420bde7f78c416b90be11db94cb789979nd </author>

b686b6a420bde7f78c416b90be11db94cb789979nd </authorgroup>

b686b6a420bde7f78c416b90be11db94cb789979nd </refentryinfo>

b686b6a420bde7f78c416b90be11db94cb789979nd

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <refmeta>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <refentrytitle>sd_notify</refentrytitle>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <manvolnum>3</manvolnum>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf </refmeta>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <refnamediv>

b686b6a420bde7f78c416b90be11db94cb789979nd <refname>sd_notify</refname>

b686b6a420bde7f78c416b90be11db94cb789979nd <refname>sd_notifyf</refname>

b686b6a420bde7f78c416b90be11db94cb789979nd <refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose>

b686b6a420bde7f78c416b90be11db94cb789979nd </refnamediv>

117c1f888a14e73cdd821dc6c23eb0411144a41cnd

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <refsynopsisdiv>

b686b6a420bde7f78c416b90be11db94cb789979nd <funcsynopsis>

b686b6a420bde7f78c416b90be11db94cb789979nd <funcsynopsisinfo>#include "sd-daemon.h"</funcsynopsisinfo>

b686b6a420bde7f78c416b90be11db94cb789979nd

b686b6a420bde7f78c416b90be11db94cb789979nd <funcprototype>

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

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

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

b686b6a420bde7f78c416b90be11db94cb789979nd </funcprototype>

b686b6a420bde7f78c416b90be11db94cb789979nd

b686b6a420bde7f78c416b90be11db94cb789979nd <funcprototype>

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

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

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

b686b6a420bde7f78c416b90be11db94cb789979nd <paramdef>...</paramdef>

b686b6a420bde7f78c416b90be11db94cb789979nd </funcprototype>

b686b6a420bde7f78c416b90be11db94cb789979nd </funcsynopsis>

b686b6a420bde7f78c416b90be11db94cb789979nd </refsynopsisdiv>

b686b6a420bde7f78c416b90be11db94cb789979nd

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <refsect1>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <title>Description</title>

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <para><function>sd_notify()</function> shall be called

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf by a daemon to notify the init system about status

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen changes. It can be used to send arbitrary information,

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd encoded in an environment-block-like string. Most

e487d6c09669296f94a5190cc34586a98e624a00nd importantly it can be used for start-up completion

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd notification.</para>

17ade6df5ec233536985eb1c130a906c725dd614humbedooh

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

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

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

b686b6a420bde7f78c416b90be11db94cb789979nd environment variable before returning (regardless

b686b6a420bde7f78c416b90be11db94cb789979nd whether the function call itself succeeded or

b686b6a420bde7f78c416b90be11db94cb789979nd not). Further calls to

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

b686b6a420bde7f78c416b90be11db94cb789979nd the variable is no longer inherited by child

b686b6a420bde7f78c416b90be11db94cb789979nd processes.</para>

b686b6a420bde7f78c416b90be11db94cb789979nd

b686b6a420bde7f78c416b90be11db94cb789979nd <para>The <parameter>state</parameter> parameter

b686b6a420bde7f78c416b90be11db94cb789979nd should contain an newline-seperated list of variable

b686b6a420bde7f78c416b90be11db94cb789979nd assignments, similar in style to an environment

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf block. A trailing newline is implied if none is

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen specified. The string may contain any kind of variable

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd assignments, but the following shall be considered

e487d6c09669296f94a5190cc34586a98e624a00nd well-known:</para>

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd

17ade6df5ec233536985eb1c130a906c725dd614humbedooh <variablelist>

e487d6c09669296f94a5190cc34586a98e624a00nd <varlistentry>

b686b6a420bde7f78c416b90be11db94cb789979nd <term>READY=1</term>

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener <listitem><para>Tells the init system

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener that daemon startup is finished. This

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener is only used by systemd if the service

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf definition file has Type=notify

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener set. The passed argument is a boolean

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener "1" or "0". Since there is little

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener value in signalling non-readiness, the

9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf only value daemons should send is

c6e6ef7c81b1ac917bb7a994557908225bac491ecovener "READY=1".</para></listitem>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen </varlistentry>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen <varlistentry>

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

b686b6a420bde7f78c416b90be11db94cb789979nd

b686b6a420bde7f78c416b90be11db94cb789979nd <listitem><para>Passes a single-line

b686b6a420bde7f78c416b90be11db94cb789979nd status string back to the init system

b686b6a420bde7f78c416b90be11db94cb789979nd that describes the daemon state. This

b686b6a420bde7f78c416b90be11db94cb789979nd is free-form and can be used for

b686b6a420bde7f78c416b90be11db94cb789979nd various purposes: general state

b686b6a420bde7f78c416b90be11db94cb789979nd feedback, fsck-like programs could

b686b6a420bde7f78c416b90be11db94cb789979nd pass completion percentages and

b686b6a420bde7f78c416b90be11db94cb789979nd failing programs could pass a human

b686b6a420bde7f78c416b90be11db94cb789979nd readable error message. Example:

b686b6a420bde7f78c416b90be11db94cb789979nd "STATUS=Completed 66% of file system

b686b6a420bde7f78c416b90be11db94cb789979nd check..."</para></listitem>

fd09dcc9b954fde7abde7955af4ba9a094d34d50rbowen </varlistentry>

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd <varlistentry>

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

e55e60efce8a3e2139132c1d6ad9f6f0d2976614nd

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

e487d6c09669296f94a5190cc34586a98e624a00nd errno-style error code, formatted as

b686b6a420bde7f78c416b90be11db94cb789979nd string. Example: "ERRNO=2" for

b686b6a420bde7f78c416b90be11db94cb789979nd ENOENT.</para></listitem>

b686b6a420bde7f78c416b90be11db94cb789979nd </varlistentry>

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd <varlistentry>

0066eddda7203f6345b56f77d146a759298dc635gryzor <term>BUSERROR=...</term>

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd

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

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung D-Bus error-style error code. Example:

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

5effc8b39fae5cd169d17f342bfc265705840014rbowen </varlistentry>

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen

2c9e74eac9f72c14535dd65a520e4de2e664d9cdhumbedooh <varlistentry>

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

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen

d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen <listitem><para>The main pid of the

b686b6a420bde7f78c416b90be11db94cb789979nd daemon, in case the init system did

not fork off the process

itself. Example:

"MAINPID=4711"</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_notifyf()</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 algorithm check the

liberally licensed reference implementation sources:

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

resp. <ulink

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

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

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

the reference implementation's drop-in

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

<filename>sd-daemon.h</filename> files. It is

recommended that applications consuming these APIs

copy the implementation into their source tree. For

more details about the reference implementation see

<citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>

<para>If -DDISABLE_SYSTEMD is set during compilation

this function 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 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>7</manvolnum></citerefentry>,

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

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

</para>

</refsect1>

</refentry>