X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_notify.xml;h=f3f3269769bdee77fd56f301a63d81444c013df0;hb=e7082c89f1eac3ee251e659ee004f4d29fc284a6;hp=03efe0193a7501bfd3bb4863feaa1903bc335156;hpb=35eec258c4523c92fe985d764198b266ebc3881a;p=elogind.git

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 03efe0193..f3f326976 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -66,7 +66,7 @@
         <funcdef>int <function>sd_notifyf</function></funcdef>
         <paramdef>int <parameter>unset_environment</parameter></paramdef>
         <paramdef>const char *<parameter>format</parameter></paramdef>
-        <paramdef>...</paramdef>
+        <paramdef>…</paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -81,7 +81,7 @@
         <paramdef>pid_t <parameter>pid</parameter></paramdef>
         <paramdef>int <parameter>unset_environment</parameter></paramdef>
         <paramdef>const char *<parameter>format</parameter></paramdef>
-        <paramdef>...</paramdef>
+        <paramdef>…</paramdef>
       </funcprototype>
 
       <funcprototype>
@@ -152,7 +152,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term>STATUS=...</term>
+        <term>STATUS=…</term>
 
         <listitem><para>Passes a single-line UTF-8 status string back
         to the service manager that describes the service state. This
@@ -160,11 +160,11 @@
         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>
+        system check…</literal></para></listitem>
       </varlistentry>
 
       <varlistentry>
-        <term>ERRNO=...</term>
+        <term>ERRNO=…</term>
 
         <listitem><para>If a service fails, the errno-style error
         code, formatted as string. Example: <literal>ERRNO=2</literal>
@@ -172,7 +172,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term>BUSERROR=...</term>
+        <term>BUSERROR=…</term>
 
         <listitem><para>If a service fails, the D-Bus error-style
         error code. Example:
@@ -180,7 +180,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term>MAINPID=...</term>
+        <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.
@@ -205,32 +205,29 @@
       <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>
+        <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 will 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>).
+        File descriptors must be pollable, see
+        <citerefentry><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+        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>
 
       <varlistentry>
-        <term>FDNAME=...</term>
+        <term>FDNAME=…</term>
 
         <listitem><para>When used in combination with
         <varname>FDSTORE=1</varname>, specifies a name for the
@@ -251,7 +248,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term>WATCHDOG_USEC=...</term>
+        <term>WATCHDOG_USEC=…</term>
 
         <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
         Notice that this is not available when using <function>sd_event_set_watchdog()</function>
@@ -271,6 +268,15 @@
     <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for details.</para>
 
+    <para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
+    the sending process is still around at the time PID 1 processes the message, or if the sending process is
+    explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
+    off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
+    <varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
+    <function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
+    attribute the message to the unit, and thus will ignore it, even if
+    <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
+
     <para><function>sd_notifyf()</function> is similar to
     <function>sd_notify()</function> but takes a
     <function>printf()</function>-like format string plus
@@ -365,7 +371,7 @@
       initialization:</para>
 
       <programlisting>sd_notifyf(0, "READY=1\n"
-        "STATUS=Processing requests...\n"
+        "STATUS=Processing requests…\n"
         "MAINPID=%lu",
         (unsigned long) getpid());</programlisting>
     </example>