[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"
        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>
Commit	Line	Data
663996b3 MS	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
	11	under the terms of the GNU Lesser General Public License as published by
	12	the Free Software Foundation; either version 2.1 of the License, or
	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
	18	Lesser General Public License for more details.
	19
	20	You should have received a copy of the GNU Lesser General Public License
	21	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	22	-->
	23
60f067b4 JS	24	<refentry id="sd_notify"
60f067b4 JS	25	xmlns:xi="http://www.w3.org/2001/XInclude">
663996b3 MS	26
	27	<refentryinfo>
	28	<title>sd_notify</title>
	29	<productname>systemd</productname>
	30
	31	<authorgroup>
	32	<author>
	33	<contrib>Developer</contrib>
	34	<firstname>Lennart</firstname>
	35	<surname>Poettering</surname>
	36	<email>lennart@poettering.net</email>
	37	</author>
	38	</authorgroup>
	39	</refentryinfo>
	40
	41	<refmeta>
	42	<refentrytitle>sd_notify</refentrytitle>
	43	<manvolnum>3</manvolnum>
	44	</refmeta>
	45
	46	<refnamediv>
	47	<refname>sd_notify</refname>
	48	<refname>sd_notifyf</refname>
5eef597e	49	<refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
663996b3 MS	50	</refnamediv>
	51
	52	<refsynopsisdiv>
	53	<funcsynopsis>
	54	<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
	55
	56	<funcprototype>
	57	<funcdef>int <function>sd_notify</function></funcdef>
	58	<paramdef>int <parameter>unset_environment</parameter></paramdef>
	59	<paramdef>const char *<parameter>state</parameter></paramdef>
	60	</funcprototype>
	61
	62	<funcprototype>
	63	<funcdef>int <function>sd_notifyf</function></funcdef>
	64	<paramdef>int <parameter>unset_environment</parameter></paramdef>
	65	<paramdef>const char *<parameter>format</parameter></paramdef>
	66	<paramdef>...</paramdef>
	67	</funcprototype>
	68	</funcsynopsis>
	69	</refsynopsisdiv>
	70
	71	<refsect1>
	72	<title>Description</title>
5eef597e MP	73	<para><function>sd_notify()</function> may be called
	74	by a service to notify the service manager about
	75	state changes. It can be used to send arbitrary
	76	information, encoded in an environment-block-like
	77	string. Most importantly it can be used for start-up
	78	completion notification.</para>
663996b3 MS	79
663996b3 MS	80	<para>If the <parameter>unset_environment</parameter>
14228c0d	81	parameter is non-zero, <function>sd_notify()</function>
663996b3	82	will unset the <varname>$NOTIFY_SOCKET</varname>
60f067b4	83	environment variable before returning (regardless of
663996b3 MS	84	whether the function call itself succeeded or
	85	not). Further calls to
	86	<function>sd_notify()</function> will then fail, but
	87	the variable is no longer inherited by child
	88	processes.</para>
	89
	90	<para>The <parameter>state</parameter> parameter
	91	should contain a newline-separated list of variable
	92	assignments, similar in style to an environment
	93	block. A trailing newline is implied if none is
	94	specified. The string may contain any kind of variable
	95	assignments, but the following shall be considered
	96	well-known:</para>
	97
	98	<variablelist>
	99	<varlistentry>
	100	<term>READY=1</term>
	101
5eef597e MP	102	<listitem><para>Tells the service
	103	manager that service startup is
	104	finished. This is only used by systemd
	105	if the service definition file has
	106	Type=notify set. Since there is little
663996b3	107	value in signaling non-readiness, the
5eef597e MP	108	only value services should send is
	109	<literal>READY=1</literal>
	110	(i.e. <literal>READY=0</literal> is
	111	not defined).</para></listitem>
	112	</varlistentry>
	113
	114	<varlistentry>
	115	<term>RELOADING=1</term>
	116
	117	<listitem><para>Tells the service manager
	118	that the service is reloading its
	119	configuration. This is useful to allow
	120	the service manager to track the service's
	121	internal state, and present it to the
	122	user. Note that a service that sends
	123	this notification must also send a
	124	<literal>READY=1</literal>
	125	notification when it completed
	126	reloading its
	127	configuration.</para></listitem>
	128	</varlistentry>
	129
	130	<varlistentry>
	131	<term>STOPPING=1</term>
	132
	133	<listitem><para>Tells the service manager
	134	that the service is beginning its
	135	shutdown. This is useful to allow the
	136	service manager to track the service's
	137	internal state, and present it to the
	138	user.</para></listitem>
663996b3 MS	139	</varlistentry>
	140
	141	<varlistentry>
	142	<term>STATUS=...</term>
	143
	144	<listitem><para>Passes a single-line
5eef597e MP	145	UTF-8 status string back to the service manager
5eef597e MP	146	that describes the service state. This
663996b3 MS	147	is free-form and can be used for
	148	various purposes: general state
	149	feedback, fsck-like programs could
	150	pass completion percentages and
	151	failing programs could pass a human
	152	readable error message. Example:
5eef597e MP	153	<literal>STATUS=Completed 66% of file
	154	system
	155	check...</literal></para></listitem>
663996b3 MS	156	</varlistentry>
	157
	158	<varlistentry>
	159	<term>ERRNO=...</term>
	160
5eef597e	161	<listitem><para>If a service fails, the
663996b3	162	errno-style error code, formatted as
5eef597e	163	string. Example: <literal>ERRNO=2</literal> for
663996b3 MS	164	ENOENT.</para></listitem>
	165	</varlistentry>
	166
	167	<varlistentry>
	168	<term>BUSERROR=...</term>
	169
5eef597e	170	<listitem><para>If a service fails, the
663996b3	171	D-Bus error-style error code. Example:
5eef597e	172	<literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
663996b3 MS	173	</varlistentry>
	174
	175	<varlistentry>
	176	<term>MAINPID=...</term>
	177
	178	<listitem><para>The main pid of the
5eef597e	179	service, in case the service manager did
663996b3 MS	180	not fork off the process
663996b3 MS	181	itself. Example:
5eef597e	182	<literal>MAINPID=4711</literal></para></listitem>
663996b3 MS	183	</varlistentry>
	184
	185	<varlistentry>
	186	<term>WATCHDOG=1</term>
	187
	188	<listitem><para>Tells systemd to
	189	update the watchdog timestamp. This is
	190	the keep-alive ping that services need
	191	to issue in regular intervals if
	192	<varname>WatchdogSec=</varname> is
	193	enabled for it. See
	194	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
5eef597e MP	195	for information how to enable this
5eef597e MP	196	functionality and
60f067b4	197	<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
5eef597e MP	198	for the details of how the service can
	199	check if the the watchdog is enabled.
	200	</para></listitem>
663996b3 MS	201	</varlistentry>
	202	</variablelist>
	203
	204	<para>It is recommended to prefix variable names that
	205	are not shown in the list above with
	206	<varname>X_</varname> to avoid namespace
	207	clashes.</para>
	208
	209	<para>Note that systemd will accept status data sent
5eef597e	210	from a service only if the
663996b3 MS	211	<varname>NotifyAccess=</varname> option is correctly
	212	set in the service definition file. See
	213	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	214	for details.</para>
	215
	216	<para><function>sd_notifyf()</function> is similar to
	217	<function>sd_notify()</function> but takes a
	218	<function>printf()</function>-like format string plus
	219	arguments.</para>
	220	</refsect1>
	221
	222	<refsect1>
	223	<title>Return Value</title>
	224
	225	<para>On failure, these calls return a negative
	226	errno-style error code. If
	227	<varname>$NOTIFY_SOCKET</varname> was not set and
	228	hence no status data could be sent, 0 is returned. If
14228c0d	229	the status was sent, these functions return with a
663996b3 MS	230	positive return value. In order to support both, init
663996b3 MS	231	systems that implement this scheme and those which
14228c0d	232	do not, it is generally recommended to ignore the return
663996b3 MS	233	value of this call.</para>
	234	</refsect1>
	235
	236	<refsect1>
	237	<title>Notes</title>
	238
60f067b4	239	<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
663996b3 MS	240
	241	<para>Internally, these functions send a single
	242	datagram with the state string as payload to the
14228c0d	243	<constant>AF_UNIX</constant> socket referenced in the
663996b3 MS	244	<varname>$NOTIFY_SOCKET</varname> environment
663996b3 MS	245	variable. If the first character of
14228c0d	246	<varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the string is
663996b3 MS	247	understood as Linux abstract namespace socket. The
663996b3 MS	248	datagram is accompanied by the process credentials of
5eef597e	249	the sending service, using SCM_CREDENTIALS.</para>
663996b3 MS	250	</refsect1>
	251
	252	<refsect1>
	253	<title>Environment</title>
	254
	255	<variablelist class='environment-variables'>
	256	<varlistentry>
	257	<term><varname>$NOTIFY_SOCKET</varname></term>
	258
5eef597e	259	<listitem><para>Set by the service manager
663996b3 MS	260	for supervised processes for status
	261	and start-up completion
	262	notification. This environment variable
	263	specifies the socket
	264	<function>sd_notify()</function> talks
	265	to. See above for details.</para></listitem>
	266	</varlistentry>
	267	</variablelist>
	268	</refsect1>
	269
	270	<refsect1>
	271	<title>Examples</title>
	272
	273	<example>
	274	<title>Start-up Notification</title>
	275
5eef597e	276	<para>When a service finished starting up, it
663996b3	277	might issue the following call to notify
5eef597e	278	the service manager:</para>
663996b3 MS	279
	280	<programlisting>sd_notify(0, "READY=1");</programlisting>
	281	</example>
	282
	283	<example>
	284	<title>Extended Start-up Notification</title>
	285
5eef597e	286	<para>A service could send the following after
663996b3 MS	287	completing initialization:</para>
	288
	289	<programlisting>sd_notifyf(0, "READY=1\n"
	290	"STATUS=Processing requests...\n"
	291	"MAINPID=%lu",
	292	(unsigned long) getpid());</programlisting>
	293	</example>
	294
	295	<example>
	296	<title>Error Cause Notification</title>
	297
5eef597e	298	<para>A service could send the following shortly before exiting, on failure</para>
663996b3 MS	299
	300	<programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n"
	301	"ERRNO=%i",
	302	strerror(errno),
	303	errno);</programlisting>
	304	</example>
	305	</refsect1>
	306
	307	<refsect1>
	308	<title>See Also</title>
	309	<para>
	310	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	311	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
	312	<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
60f067b4 JS	313	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
60f067b4 JS	314	<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
663996b3 MS	315	</para>
	316	</refsect1>
	317
	318	</refentry>