man: xinclude pkg-config note

[thirdparty/systemd.git] / man / systemd-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="systemd-notify"
          xmlns:xi="http://www.w3.org/2001/XInclude">

        <refentryinfo>
                <title>systemd-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>systemd-notify</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd-notify</refname>
                <refpurpose>Notify service manager about start-up completion and other daemon status changes</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <cmdsynopsis>
                        <command>systemd-notify <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
                </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><command>systemd-notify</command> may be
                called by daemon scripts to notify the init system
                about status changes. It can be used to send arbitrary
                information, encoded in an environment-block-like list
                of strings. Most importantly it can be used for
                start-up completion notification.</para>

                <para>This is mostly just a wrapper around
                <function>sd_notify()</function> and makes this
                functionality available to shell scripts. For details
                see
                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

                <para>The command line may carry a list of
                environment variables to send as part of the status
                update.</para>

                <para>Note that systemd will refuse reception of
                status updates from this command unless
                <varname>NotifyAccess=all</varname> is set for the
                service unit this command is called from.</para>

        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>The following options are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><option>--ready</option></term>

                                <listitem><para>Inform the init system
                                about service start-up
                                completion. This is equivalent to
                                <command>systemd-notify
                                READY=1</command>. For details about
                                the semantics of this option see
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--pid=</option></term>

                                <listitem><para>Inform the init system
                                about the main PID of the
                                daemon. Takes a PID as argument. If
                                the argument is omitted, the PID of the
                                process that invoked
                                <command>systemd-notify</command> is
                                used. This is equivalent to
                                <command>systemd-notify
                                MAINPID=$PID</command>. For details
                                about the semantics of this option see
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--status=</option></term>

                                <listitem><para>Send a free-form
                                status string for the daemon to the
                                init systemd. This option takes the
                                status string as argument. This is
                                equivalent to <command>systemd-notify
                                STATUS=...</command>. For details
                                about the semantics of this option see
                                <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--booted</option></term>

                                <listitem><para>Returns 0 if the
                                system was booted up with systemd,
                                non-zero otherwise. If this option is
                                passed, no message is sent. This option
                                is hence unrelated to the other
                                options. For details about the
                                semantics of this option, see
                                <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--readahead=</option></term>

                                <listitem><para>Controls disk
                                read-ahead operations. The argument
                                must be a string, and either "cancel",
                                "done" or "noreplay". For details
                                about the semantics of this option see
                                <citerefentry><refentrytitle>sd_readahead</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
                        </varlistentry>

                        <xi:include href="standard-options.xml" xpointer="help" />
                        <xi:include href="standard-options.xml" xpointer="version" />
                </variablelist>

        </refsect1>

        <refsect1>
                <title>Exit status</title>

                <para>On success, 0 is returned, a non-zero failure
                code otherwise.</para>
        </refsect1>

        <refsect1>
                <title>Example</title>

                <example>
                        <title>Start-up Notification and Status Updates</title>

                        <para>A simple shell daemon that sends
                        start-up notifications after having set up its
                        communication channel. During runtime it sends
                        further status updates to the init
                        system:</para>

                        <programlisting>#!/bin/bash

mkfifo /tmp/waldo
systemd-notify --ready --status="Waiting for data..."

while : ; do
        read a &lt; /tmp/waldo
        systemd-notify --status="Processing $a"

        # Do something with $a ...

        systemd-notify --status="Waiting for data..."
done</programlisting>
                </example>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_booted</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>