[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 init system 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.
                                Services using this feature should do
                                this in regular intervals. A watchdog
                                framework can use the timestamps to
                                detect failed
                                services.</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>7</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>7</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>
	48	<refpurpose>Notify init system about start-up completion and other daemon status changes</refpurpose>
	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
96d4ce01	90	should contain an 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
af62c704	107	value in signalling 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
	159	update the watchdog timestamp.
	160	Services using this feature should do
	161	this in regular intervals. A watchdog
	162	framework can use the timestamps to
	163	detect failed
	164	services.</para></listitem>
	165	</varlistentry>
f9378423 LP	166	</variablelist>
f9378423 LP	167
436c44a5	168	<para>It is recommended to prefix variable names that
f9378423 LP	169	are not shown in the list above with
	170	<varname>X_</varname> to avoid namespace
	171	clashes.</para>
	172
	173	<para>Note that systemd will accept status data sent
	174	from a daemon only if the
	175	<varname>NotifyAccess=</varname> option is correctly
	176	set in the service definition file. See
	177	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	178	for details.</para>
	179
	180	<para><function>sd_notifyf()</function> is similar to
9f846242	181	<function>sd_notify()</function> but takes a
f9378423 LP	182	<function>printf()</function>-like format string plus
	183	arguments.</para>
	184	</refsect1>
	185
	186	<refsect1>
	187	<title>Return Value</title>
	188
	189	<para>On failure, these calls return a negative
	190	errno-style error code. If
	191	<varname>$NOTIFY_SOCKET</varname> was not set and
af62c704	192	hence no status data could be sent, 0 is returned. If
f9378423	193	the status was sent these functions return with a
af62c704	194	positive return value. In order to support both, init
f9378423	195	systems that implement this scheme and those which
af62c704	196	don't, it is generally recommended to ignore the return
f9378423 LP	197	value of this call.</para>
	198	</refsect1>
	199
	200	<refsect1>
	201	<title>Notes</title>
	202
	203	<para>These functions are provided by the reference
	204	implementation of APIs for new-style daemons and
	205	distributed with the systemd package. The algorithms
	206	they implement are simple, and can easily be
	207	reimplemented in daemons if it is important to support
	208	this interface without using the reference
	209	implementation.</para>
	210
	211	<para>Internally, these functions send a single
	212	datagram with the state string as payload to the
	213	AF_UNIX socket referenced in the
	214	<varname>$NOTIFY_SOCKET</varname> environment
	215	variable. If the first character of
	216	<varname>$NOTIFY_SOCKET</varname> is @ the string is
	217	understood as Linux abstract namespace socket. The
	218	datagram is accompanied by the process credentials of
	219	the sending daemon, using SCM_CREDENTIALS.</para>
	220
71e6c1cf	221	<para>For details about the algorithms check the
f9378423	222	liberally licensed reference implementation sources:
a26c9cc6	223	<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>
f9378423	224	resp. <ulink
a26c9cc6	225	url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
f9378423 LP	226
	227	<para><function>sd_notify()</function> and
	228	<function>sd_notifyf()</function> are implemented in
71e6c1cf	229	the reference implementation's
f9378423	230	<filename>sd-daemon.c</filename> and
71e6c1cf LP	231	<filename>sd-daemon.h</filename> files. These
	232	interfaces are available as shared library, which can
	233	be compiled and linked to with the
	234	<literal>libsystemd-daemon</literal>
	235	<citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	236	file. Alternatively, applications consuming these APIs
	237	may copy the implementation into their source tree. For
f9378423	238	more details about the reference implementation see
71e6c1cf	239	<citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
f9378423	240
71e6c1cf LP	241	<para>If the reference implementation is used as
	242	drop-in files and -DDISABLE_SYSTEMD is set during
	243	compilation these functions will always return 0 and
	244	otherwise become a NOP.</para>
f9378423 LP	245	</refsect1>
f9378423 LP	246
7874bcd6 LP	247	<refsect1>
	248	<title>Environment</title>
	249
	250	<variablelist>
	251	<varlistentry>
	252	<term><varname>$NOTIFY_SOCKET</varname></term>
	253
	254	<listitem><para>Set by the init system
	255	for supervised processes for status
	256	and start-up completion
	257	notification. This environment variable
	258	specifies the socket
	259	<function>sd_notify()</function> talks
	260	to. See above for details.</para></listitem>
	261	</varlistentry>
	262	</variablelist>
	263	</refsect1>
	264
f9378423 LP	265	<refsect1>
	266	<title>Examples</title>
	267
	268	<example>
	269	<title>Start-up Notification</title>
	270
	271	<para>When a daemon finished starting up, it
ad678a06	272	might issue the following call to notify
f9378423 LP	273	the init system:</para>
	274
	275	<programlisting>sd_notify(0, "READY=1");</programlisting>
	276	</example>
	277
	278	<example>
	279	<title>Extended Start-up Notification</title>
	280
	281	<para>A daemon could send the following after
	282	completing initialization:</para>
	283
	284	<programlisting>sd_notifyf(0, "READY=1\n"
	285	"STATUS=Processing requests...\n"
	286	"MAINPID=%lu",
	287	(unsigned long) getpid());</programlisting>
	288	</example>
	289
	290	<example>
	291	<title>Error Cause Notification</title>
	292
	293	<para>A daemon could send the following shortly before exiting, on failure</para>
	294
	295	<programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
	296	"ERRNO=%i",
	297	strerror(errno),
	298	errno);</programlisting>
	299	</example>
	300	</refsect1>
	301
	302	<refsect1>
	303	<title>See Also</title>
	304	<para>
160cd5c9	305	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f9378423 LP	306	<citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423 LP	307	<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
f9378423 LP	308	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	309	</para>
	310	</refsect1>
	311
	312	</refentry>