mirror of
https://github.com/systemd/systemd.git
synced 2025-02-28 05:57:33 +03:00
man/sd_notify: split out variable descriptions to a separate section
This just moves the text around with miminal text added to refer to the new section.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
4454ca1057
commit
ef86486acf
@ -109,8 +109,69 @@
|
||||
|
||||
<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>
|
||||
specified. The string may contain any kind of variable assignments, but see the next section
|
||||
for a list of assignments understood by the service manager.</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>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>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of
|
||||
notifications to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as
|
||||
a synchronization point and ensures all notifications sent before this call have been picked up by the
|
||||
service manager when it returns successfully. Use of <function>sd_notify_barrier()</function> is needed
|
||||
for clients which are not invoked by the service manager, otherwise this synchronization mechanism is
|
||||
unnecessary for attribution of notifications to the unit.</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 file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
|
||||
immediately closed on reception.</para>
|
||||
|
||||
<para><function>sd_pid_notifyf_with_fds()</function> is a combination of
|
||||
<function>sd_pid_notify_with_fds()</function> and <function>sd_notifyf()</function>, i.e. it accepts both
|
||||
a PID and a set of file descriptors as input, and processes a format string to generate the state
|
||||
string.</para>
|
||||
|
||||
<para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of
|
||||
previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a
|
||||
relative <varname>timeout</varname> value in microseconds which is passed to
|
||||
<citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.</para>
|
||||
|
||||
<para><function>sd_pid_notify_barrier()</function> is just like <function>sd_notify_barrier()</function>,
|
||||
but allows specifying the originating PID for the notification message.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Well-known assignments</title>
|
||||
|
||||
<para>The following assignments have a defined meaning:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
@ -126,9 +187,9 @@
|
||||
<varlistentry>
|
||||
<term>RELOADING=1</term>
|
||||
|
||||
<listitem><para>Tells the service manager that the service is beginning to reload 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
|
||||
<listitem><para>Tells the service manager that the service is beginning to reload 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. Reloads the
|
||||
service manager is notified about with this mechanisms are propagated in the same way as they are
|
||||
when originally initiated through the service manager. This message is particularly relevant for
|
||||
@ -138,6 +199,16 @@
|
||||
<xi:include href="version-info.xml" xpointer="v217"/></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>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>MONOTONIC_USEC=…</term>
|
||||
|
||||
@ -151,24 +222,13 @@
|
||||
<xi:include href="version-info.xml" xpointer="v253"/></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>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v217"/></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>
|
||||
error message. Example: <literal>STATUS=Completed 66% of file system check…</literal></para>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||||
</varlistentry>
|
||||
@ -179,8 +239,8 @@
|
||||
<listitem><para>Reset the access to the service status notification socket during runtime, overriding
|
||||
<varname>NotifyAccess=</varname> setting in the service unit file. See
|
||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for details, specifically <literal>NotifyAccess=</literal> for a list of accepted
|
||||
values.</para>
|
||||
for details, specifically <literal>NotifyAccess=</literal> for a list of accepted values.
|
||||
</para>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
||||
</varlistentry>
|
||||
@ -216,7 +276,7 @@
|
||||
<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>
|
||||
off the process itself. Example: <literal>MAINPID=4711</literal>.</para>
|
||||
|
||||
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
|
||||
</varlistentry>
|
||||
@ -361,63 +421,8 @@
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>It is recommended to prefix variable names that are not listed above with <varname>X_</varname> to
|
||||
<para>It is recommended to prefix variable names that are not listed above with <literal>X_</literal> 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>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>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of
|
||||
notifications to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as
|
||||
a synchronization point and ensures all notifications sent before this call have been picked up by the
|
||||
service manager when it returns successfully. Use of <function>sd_notify_barrier()</function> is needed
|
||||
for clients which are not invoked by the service manager, otherwise this synchronization mechanism is
|
||||
unnecessary for attribution of notifications to the unit.</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 file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
|
||||
immediately closed on reception.</para>
|
||||
|
||||
<para><function>sd_pid_notifyf_with_fds()</function> is a combination of
|
||||
<function>sd_pid_notify_with_fds()</function> and <function>sd_notifyf()</function>, i.e. it accepts both
|
||||
a PID and a set of file descriptors as input, and processes a format string to generate the state
|
||||
string.</para>
|
||||
|
||||
<para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of
|
||||
previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a
|
||||
relative <varname>timeout</varname> value in microseconds which is passed to
|
||||
<citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
|
||||
</citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.</para>
|
||||
|
||||
<para><function>sd_pid_notify_barrier()</function> is just like <function>sd_notify_barrier()</function>,
|
||||
but allows specifying the originating PID for the notification message.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user