diff options
Diffstat (limited to 'man/systemd-notify.xml')
| -rw-r--r-- | man/systemd-notify.xml | 310 |
1 files changed, 147 insertions, 163 deletions
diff --git a/man/systemd-notify.xml b/man/systemd-notify.xml index 684f490099..06d5ae5319 100644 --- a/man/systemd-notify.xml +++ b/man/systemd-notify.xml @@ -1,6 +1,6 @@ <?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"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -22,175 +22,159 @@ --> <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> - - <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 + 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> + + <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 < /tmp/waldo - systemd-notify --status="Processing $a" + read a < /tmp/waldo + systemd-notify --status="Processing $a" - # Do something with $a ... + # Do something with $a ... - systemd-notify --status="Waiting for data..." + 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> + </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> |