man/sd_notify.xml

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