<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>
<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>
</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
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>
</varlistentry>
<varlistentry>
- <term>BUSERROR=...</term>
+ <term>BUSERROR=…</term>
<listitem><para>If a service fails, the D-Bus error-style
error code. Example:
</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.
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>
+ <citerefentry><refentrytitle>elogind.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 whether the
<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>elogind.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
</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>
<para>Note that elogind 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>
+ <citerefentry><refentrytitle>elogind.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
initialization:</para>
<programlisting>sd_notifyf(0, "READY=1\n"
- "STATUS=Processing requests...\n"
+ "STATUS=Processing requests…\n"
"MAINPID=%lu",
(unsigned long) getpid());</programlisting>
</example>
<refsect1>
<title>See Also</title>
<para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff