[thirdparty/systemd.git] / man / sd_notify.xml

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

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<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 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 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".</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
                <constant>AF_UNIX</constant> 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/libsystemd-daemon/sd-daemon.c"/>
                and <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
                <constant>libsystemd-daemon</constant>
                <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 class='environment-variables'>
                        <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>
Commit	Line	Data
f9378423 LP	1	<?xml version='1.0'?> <!---nxml--->
	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	4
	5	<!--
	6	This file is part of systemd.
	7
	8	Copyright 2010 Lennart Poettering
	9
	10	systemd is free software; you can redistribute it and/or modify it
5430f7f2 LP	11	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	12	the Free Software Foundation; either version 2.1 of the License, or
f9378423 LP	13	(at your option) any later version.
	14
	15	systemd is distributed in the hope that it will be useful, but
	16	WITHOUT ANY WARRANTY; without even the implied warranty of
	17	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2	18	Lesser General Public License for more details.
f9378423	19
5430f7f2	20	You should have received a copy of the GNU Lesser General Public License
f9378423 LP	21	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	22	-->
	23
	24	<refentry id="sd_notify">
	25
	26	<refentryinfo>
	27	<title>sd_notify</title>
	28	<productname>systemd</productname>
	29
	30	<authorgroup>
	31	<author>
	32	<contrib>Developer</contrib>
	33	<firstname>Lennart</firstname>
	34	<surname>Poettering</surname>
	35	<email>lennart@poettering.net</email>
	36	</author>
	37	</authorgroup>
	38	</refentryinfo>
	39
	40	<refmeta>
	41	<refentrytitle>sd_notify</refentrytitle>
	42	<manvolnum>3</manvolnum>
	43	</refmeta>
	44
	45	<refnamediv>
	46	<refname>sd_notify</refname>
	47	<refname>sd_notifyf</refname>
34511ca7	48	<refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
f9378423 LP	49	</refnamediv>
	50
	51	<refsynopsisdiv>
	52	<funcsynopsis>
a822cbfa	53	<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
f9378423 LP	54
	55	<funcprototype>
	56	<funcdef>int <function>sd_notify</function></funcdef>
	57	<paramdef>int <parameter>unset_environment</parameter></paramdef>
	58	<paramdef>const char *<parameter>state</parameter></paramdef>
	59	</funcprototype>
	60
	61	<funcprototype>
	62	<funcdef>int <function>sd_notifyf</function></funcdef>
	63	<paramdef>int <parameter>unset_environment</parameter></paramdef>
	64	<paramdef>const char *<parameter>format</parameter></paramdef>
	65	<paramdef>...</paramdef>
	66	</funcprototype>
	67	</funcsynopsis>
	68	</refsynopsisdiv>
	69
	70	<refsect1>
	71	<title>Description</title>
	72	<para><function>sd_notify()</function> shall be called
	73	by a daemon to notify the init system about status
	74	changes. It can be used to send arbitrary information,
	75	encoded in an environment-block-like string. Most
	76	importantly it can be used for start-up completion
	77	notification.</para>
	78
	79	<para>If the <parameter>unset_environment</parameter>
	80	parameter is non-zero <function>sd_notify()</function>
	81	will unset the <varname>$NOTIFY_SOCKET</varname>
	82	environment variable before returning (regardless
	83	whether the function call itself succeeded or
	84	not). Further calls to
	85	<function>sd_notify()</function> will then fail, but
	86	the variable is no longer inherited by child
	87	processes.</para>
	88
	89	<para>The <parameter>state</parameter> parameter
bb31a4ac	90	should contain a newline-separated list of variable
f9378423 LP	91	assignments, similar in style to an environment
	92	block. A trailing newline is implied if none is
	93	specified. The string may contain any kind of variable
	94	assignments, but the following shall be considered
	95	well-known:</para>
	96
	97	<variablelist>
	98	<varlistentry>
	99	<term>READY=1</term>
	100
	101	<listitem><para>Tells the init system
	102	that daemon startup is finished. This
	103	is only used by systemd if the service
	104	definition file has Type=notify
	105	set. The passed argument is a boolean
	106	"1" or "0". Since there is little
bb31a4ac	107	value in signaling non-readiness, the
f9378423 LP	108	only value daemons should send is
	109	"READY=1".</para></listitem>
	110	</varlistentry>
	111
	112	<varlistentry>
	113	<term>STATUS=...</term>
	114
	115	<listitem><para>Passes a single-line
	116	status string back to the init system
	117	that describes the daemon state. This
af62c704	118	is free-form and can be used for
f9378423 LP	119	various purposes: general state
	120	feedback, fsck-like programs could
	121	pass completion percentages and
	122	failing programs could pass a human
	123	readable error message. Example:
	124	"STATUS=Completed 66% of file system
	125	check..."</para></listitem>
	126	</varlistentry>
	127
	128	<varlistentry>
	129	<term>ERRNO=...</term>
	130
	131	<listitem><para>If a daemon fails, the
	132	errno-style error code, formatted as
	133	string. Example: "ERRNO=2" for
	134	ENOENT.</para></listitem>
	135	</varlistentry>
	136
	137	<varlistentry>
	138	<term>BUSERROR=...</term>
	139
	140	<listitem><para>If a daemon fails, the
	141	D-Bus error-style error code. Example:
	142	"BUSERROR=org.freedesktop.DBus.Error.TimedOut"</para></listitem>
	143	</varlistentry>
	144
	145	<varlistentry>
	146	<term>MAINPID=...</term>
	147
	148	<listitem><para>The main pid of the
	149	daemon, in case the init system did
	150	not fork off the process
	151	itself. Example:
	152	"MAINPID=4711"</para></listitem>
	153	</varlistentry>
a6927d7f MO	154
	155	<varlistentry>
	156	<term>WATCHDOG=1</term>
	157
	158	<listitem><para>Tells systemd to
dac051ad LP	159	update the watchdog timestamp. This is
	160	the keep-alive ping that services need
	161	to issue in regular intervals if
	162	<varname>WatchdogSec=</varname> is
	163	enabled for it. See
	164	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	165	for details. It is recommended to send
	166	this message if the
	167	<varname>WATCHDOG_USEC=</varname>
	168	environment variable has been set for
	169	the service process, in every half the
	170	time interval that is specified in the
	171	variable.</para></listitem>
a6927d7f	172	</varlistentry>
f9378423 LP	173	</variablelist>
f9378423 LP	174
436c44a5	175	<para>It is recommended to prefix variable names that
f9378423 LP	176	are not shown in the list above with
	177	<varname>X_</varname> to avoid namespace
	178	clashes.</para>
	179
	180	<para>Note that systemd will accept status data sent
	181	from a daemon only if the
	182	<varname>NotifyAccess=</varname> option is correctly
	183	set in the service definition file. See
	184	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	185	for details.</para>
	186
	187	<para><function>sd_notifyf()</function> is similar to
9f846242	188	<function>sd_notify()</function> but takes a
f9378423 LP	189	<function>printf()</function>-like format string plus
	190	arguments.</para>
	191	</refsect1>
	192
	193	<refsect1>
	194	<title>Return Value</title>
	195
	196	<para>On failure, these calls return a negative
	197	errno-style error code. If
	198	<varname>$NOTIFY_SOCKET</varname> was not set and
af62c704	199	hence no status data could be sent, 0 is returned. If
f9378423	200	the status was sent these functions return with a
af62c704	201	positive return value. In order to support both, init
f9378423	202	systems that implement this scheme and those which
af62c704	203	don't, it is generally recommended to ignore the return
f9378423 LP	204	value of this call.</para>
	205	</refsect1>
	206
	207	<refsect1>
	208	<title>Notes</title>
	209
	210	<para>These functions are provided by the reference
	211	implementation of APIs for new-style daemons and
	212	distributed with the systemd package. The algorithms
	213	they implement are simple, and can easily be
	214	reimplemented in daemons if it is important to support
	215	this interface without using the reference
	216	implementation.</para>
	217
	218	<para>Internally, these functions send a single
	219	datagram with the state string as payload to the
74d00578	220	<constant>AF_UNIX</constant> socket referenced in the
f9378423 LP	221	<varname>$NOTIFY_SOCKET</varname> environment
	222	variable. If the first character of
	223	<varname>$NOTIFY_SOCKET</varname> is @ the string is
	224	understood as Linux abstract namespace socket. The
	225	datagram is accompanied by the process credentials of
	226	the sending daemon, using SCM_CREDENTIALS.</para>
	227
71e6c1cf	228	<para>For details about the algorithms check the
f9378423	229	liberally licensed reference implementation sources:
0675cc4a	230	<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
16dad32e	231	and <ulink
a26c9cc6	232	url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
f9378423 LP	233
	234	<para><function>sd_notify()</function> and
	235	<function>sd_notifyf()</function> are implemented in
71e6c1cf	236	the reference implementation's
f9378423	237	<filename>sd-daemon.c</filename> and
71e6c1cf LP	238	<filename>sd-daemon.h</filename> files. These
	239	interfaces are available as shared library, which can
	240	be compiled and linked to with the
74d00578	241	<constant>libsystemd-daemon</constant>
71e6c1cf LP	242	<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	243	file. Alternatively, applications consuming these APIs
	244	may copy the implementation into their source tree. For
f9378423	245	more details about the reference implementation see
cb07866b	246	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
f9378423	247
71e6c1cf LP	248	<para>If the reference implementation is used as
	249	drop-in files and -DDISABLE_SYSTEMD is set during
	250	compilation these functions will always return 0 and
	251	otherwise become a NOP.</para>
f9378423 LP	252	</refsect1>
f9378423 LP	253
7874bcd6 LP	254	<refsect1>
	255	<title>Environment</title>
	256
ccc9a4f9	257	<variablelist class='environment-variables'>
7874bcd6 LP	258	<varlistentry>
	259	<term><varname>$NOTIFY_SOCKET</varname></term>
	260
	261	<listitem><para>Set by the init system
	262	for supervised processes for status
	263	and start-up completion
	264	notification. This environment variable
	265	specifies the socket
	266	<function>sd_notify()</function> talks
	267	to. See above for details.</para></listitem>
	268	</varlistentry>
	269	</variablelist>
	270	</refsect1>
	271
f9378423 LP	272	<refsect1>
	273	<title>Examples</title>
	274
	275	<example>
	276	<title>Start-up Notification</title>
	277
	278	<para>When a daemon finished starting up, it
ad678a06	279	might issue the following call to notify
f9378423 LP	280	the init system:</para>
	281
	282	<programlisting>sd_notify(0, "READY=1");</programlisting>
	283	</example>
	284
	285	<example>
	286	<title>Extended Start-up Notification</title>
	287
	288	<para>A daemon could send the following after
	289	completing initialization:</para>
	290
	291	<programlisting>sd_notifyf(0, "READY=1\n"
	292	"STATUS=Processing requests...\n"
	293	"MAINPID=%lu",
	294	(unsigned long) getpid());</programlisting>
	295	</example>
	296
	297	<example>
	298	<title>Error Cause Notification</title>
	299
	300	<para>A daemon could send the following shortly before exiting, on failure</para>
	301
	302	<programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
	303	"ERRNO=%i",
	304	strerror(errno),
	305	errno);</programlisting>
	306	</example>
	307	</refsect1>
	308
	309	<refsect1>
	310	<title>See Also</title>
	311	<para>
160cd5c9	312	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cb07866b	313	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423	314	<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423 LP	315	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	316	</para>
	317	</refsect1>
	318
	319	</refentry>