diff options
| author | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2015-02-04 03:14:13 +0100 |
|---|---|---|
| committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2015-02-04 05:11:35 +0100 |
| commit | 798d3a524ea57aaf40cb53858aaa45ec702f012d (patch) | |
| tree | f9251ab7878a180d464780d514f3ea8d4599fe6e /man/sd_notify.xml | |
| parent | tmpfiles: fix compilation without acl support (diff) | |
| download | systemd-798d3a524ea57aaf40cb53858aaa45ec702f012d.tar.xz systemd-798d3a524ea57aaf40cb53858aaa45ec702f012d.zip | |
Reindent man pages to 2ch
Diffstat (limited to 'man/sd_notify.xml')
| -rw-r--r-- | man/sd_notify.xml | 754 |
1 files changed, 351 insertions, 403 deletions
diff --git a/man/sd_notify.xml b/man/sd_notify.xml index b7c33da63a..87e59c9cc2 100644 --- a/man/sd_notify.xml +++ b/man/sd_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,407 +22,355 @@ --> <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> - <refname>sd_pid_notify</refname> - <refname>sd_pid_notifyf</refname> - <refname>sd_pid_notify_with_fds</refname> - <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></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> - - <funcprototype> - <funcdef>int <function>sd_pid_notify</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notifyf</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>format</parameter></paramdef> - <paramdef>...</paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> - <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>int <parameter>unset_environment</parameter></paramdef> - <paramdef>const char *<parameter>state</parameter></paramdef> - <paramdef>const int *<parameter>fds</parameter></paramdef> - <paramdef>unsigned <parameter>n_fds</parameter></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 process ID (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 the service manager 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> - - - <varlistentry> - <term>FDSTORE=1</term> - - <listitem><para>Stores additional file - descriptors in the service - manager. File descriptors sent this - way will be maintained per-service by - the service manager and be passed - again using the usual file descriptor - passing logic on the next invocation - of the service (see - <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). This - is useful for implementing service - restart schemes where services - serialize their state to - <filename>/run</filename>, push their - file descriptors to the system - manager, and are then restarted, - retrieving their state again via - socket passing and - <filename>/run</filename>. Note that - the service manager will accept - messages for a service only if - <varname>FileDescriptorStoreMax=</varname> - is set to non-zero for it (defaults to - zero). See - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details. Multiple arrays of file - descriptors may be sent in separate - messages, in which case the arrays are - combined. Note that the service - manager removes duplicate file - descriptors before passing them to the - service. Use - <function>sd_pid_notify_with_fds()</function> - to send messages with - <literal>FDSTORE=1</literal>, see - below.</para></listitem> - </varlistentry> - - </variablelist> - - <para>It is recommended to prefix variable names that - are not listed 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> - - <para><function>sd_pid_notify()</function> and - <function>sd_pid_notifyf()</function> are similar to - <function>sd_notify()</function> and - <function>sd_notifyf()</function> but take a process - ID (PID) to use as originating PID for the message as - first argument. This is useful to send notification - messages on behalf of other processes, provided the - appropriate privileges are available. If the PID - argument is specified as 0 the process ID of the - calling process is used, in which case the calls are - fully equivalent to <function>sd_notify()</function> - and <function>sd_notifyf()</function>.</para> - - <para><function>sd_pid_notify_with_fds()</function> is - similar to <function>sd_pid_notify()</function> but - takes an additional array of file descriptors. These - file descriptors are sent along the notification - message to the service manager. This is particularly - useful for sending <literal>FDSTORE=1</literal> - messages, as described above. The additional arguments - are a pointer to the file descriptor array plus the - number of file descriptors in the array. If the number - of file descriptors is passed as 0, the call is fully - equivalent to <function>sd_pid_notify()</function>, - i.e. no file descriptors are passed. Note that sending - file descriptors to the service manager on messages - that do not expect them (i.e. without - <literal>FDSTORE=1</literal>) they are immediately - closed on reception.</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> - - <example> - <title>Store a File Descriptor in the Service Manager</title> - - <para>To store an open file descriptor in the - service manager, in order to continue - operation after a service restart without - losing state use - <literal>FDSTORE=1</literal>:</para> - - <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</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> + 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> + <refname>sd_pid_notify</refname> + <refname>sd_pid_notifyf</refname> + <refname>sd_pid_notify_with_fds</refname> + <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></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> + + <funcprototype> + <funcdef>int <function>sd_pid_notify</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notifyf</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + <paramdef>const int *<parameter>fds</parameter></paramdef> + <paramdef>unsigned <parameter>n_fds</parameter></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 process ID (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 the service manager 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> + + + <varlistentry> + <term>FDSTORE=1</term> + + <listitem><para>Stores additional file descriptors in the + service manager. File descriptors sent this way will be + maintained per-service by the service manager and be passed + again using the usual file descriptor passing logic on the + next invocation of the service (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + This is useful for implementing service restart schemes where + services serialize their state to <filename>/run</filename>, + push their file descriptors to the system manager, and are + then restarted, retrieving their state again via socket + passing and <filename>/run</filename>. Note that the service + manager will accept messages for a service only if + <varname>FileDescriptorStoreMax=</varname> is set to non-zero + for it (defaults to zero). See + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Multiple arrays of file descriptors may be sent + in separate messages, in which case the arrays are combined. + Note that the service manager removes duplicate file + descriptors before passing them to the service. Use + <function>sd_pid_notify_with_fds()</function> to send messages + with <literal>FDSTORE=1</literal>, see + below.</para></listitem> + </varlistentry> + + </variablelist> + + <para>It is recommended to prefix variable names that are not + listed 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> + + <para><function>sd_pid_notify()</function> and + <function>sd_pid_notifyf()</function> are similar to + <function>sd_notify()</function> and + <function>sd_notifyf()</function> but take a process ID (PID) to + use as originating PID for the message as first argument. This is + useful to send notification messages on behalf of other processes, + provided the appropriate privileges are available. If the PID + argument is specified as 0 the process ID of the calling process + is used, in which case the calls are fully equivalent to + <function>sd_notify()</function> and + <function>sd_notifyf()</function>.</para> + + <para><function>sd_pid_notify_with_fds()</function> is similar to + <function>sd_pid_notify()</function> but takes an additional array + of file descriptors. These file descriptors are sent along the + notification message to the service manager. This is particularly + useful for sending <literal>FDSTORE=1</literal> messages, as + described above. The additional arguments are a pointer to the + file descriptor array plus the number of file descriptors in the + array. If the number of file descriptors is passed as 0, the call + is fully equivalent to <function>sd_pid_notify()</function>, i.e. + no file descriptors are passed. Note that sending file descriptors + to the service manager on messages that do not expect them (i.e. + without <literal>FDSTORE=1</literal>) they are immediately closed + on reception.</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> + + <example> + <title>Store a File Descriptor in the Service Manager</title> + + <para>To store an open file descriptor in the service manager, + in order to continue operation after a service restart without + losing state use <literal>FDSTORE=1</literal>:</para> + + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</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> |