mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
man: rebreak all of sd_notify(3)
No change of contents, just some rebreaking of the full file to match our current line break settings.
This commit is contained in:
Lennart Poettering
parent
75b29fda71
commit
1412ad9a81
@ -77,25 +77,20 @@
|
|||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Description</title>
|
<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
|
<para><function>sd_notify()</function> may be called by a service to notify the service manager about
|
||||||
non-zero, <function>sd_notify()</function> will unset the
|
state changes. It can be used to send arbitrary information, encoded in an environment-block-like
|
||||||
<varname>$NOTIFY_SOCKET</varname> environment variable before
|
string. Most importantly, it can be used for start-up completion notification.</para>
|
||||||
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
|
<para>If the <parameter>unset_environment</parameter> parameter is non-zero,
|
||||||
newline-separated list of variable assignments, similar in style
|
<function>sd_notify()</function> will unset the <varname>$NOTIFY_SOCKET</varname> environment variable
|
||||||
to an environment block. A trailing newline is implied if none is
|
before returning (regardless of whether the function call itself succeeded or not). Further calls to
|
||||||
specified. The string may contain any kind of variable
|
<function>sd_notify()</function> will then fail, but the variable is no longer inherited by child
|
||||||
assignments, but the following shall be considered
|
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>
|
well-known:</para>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
@ -136,102 +131,95 @@
|
|||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>STOPPING=1</term>
|
<term>STOPPING=1</term>
|
||||||
|
|
||||||
<listitem><para>Tells the service manager that the service is
|
<listitem><para>Tells the service manager that the service is beginning its shutdown. This is useful
|
||||||
beginning its shutdown. This is useful to allow the service
|
to allow the service manager to track the service's internal state, and present it to the
|
||||||
manager to track the service's internal state, and present it
|
user.</para></listitem>
|
||||||
to the user.</para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>STATUS=…</term>
|
<term>STATUS=…</term>
|
||||||
|
|
||||||
<listitem><para>Passes a single-line UTF-8 status string back
|
<listitem><para>Passes a single-line UTF-8 status string back to the service manager that describes
|
||||||
to the service manager that describes the service state. This
|
the service state. This is free-form and can be used for various purposes: general state feedback,
|
||||||
is free-form and can be used for various purposes: general
|
fsck-like programs could pass completion percentages and failing programs could pass a human-readable
|
||||||
state feedback, fsck-like programs could pass completion
|
error message. Example: <literal>STATUS=Completed 66% of file system
|
||||||
percentages and failing programs could pass a human-readable
|
check…</literal></para></listitem>
|
||||||
error message. Example: <literal>STATUS=Completed 66% of file
|
|
||||||
system check…</literal></para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>NOTIFYACCESS=…</term>
|
<term>NOTIFYACCESS=…</term>
|
||||||
|
|
||||||
<listitem><para>Reset the access to the service status notification
|
<listitem><para>Reset the access to the service status notification socket during runtime, overriding
|
||||||
socket during runtime, overriding <varname>NotifyAccess=</varname> setting
|
<varname>NotifyAccess=</varname> setting in the service unit file. See
|
||||||
in the service unit file. See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
for details, specifically <literal>NotifyAccess=</literal> for a list of
|
for details, specifically <literal>NotifyAccess=</literal> for a list of accepted
|
||||||
accepted values.</para></listitem>
|
values.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>ERRNO=…</term>
|
<term>ERRNO=…</term>
|
||||||
|
|
||||||
<listitem><para>If a service fails, the errno-style error
|
<listitem><para>If a service fails, the errno-style error code, formatted as string. Example:
|
||||||
code, formatted as string. Example: <literal>ERRNO=2</literal>
|
<literal>ERRNO=2</literal> for ENOENT.</para></listitem>
|
||||||
for ENOENT.</para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>BUSERROR=…</term>
|
<term>BUSERROR=…</term>
|
||||||
|
|
||||||
<listitem><para>If a service fails, the D-Bus error-style
|
<listitem><para>If a service fails, the D-Bus error-style error code. Example:
|
||||||
error code. Example:
|
|
||||||
<literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
|
<literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>MAINPID=…</term>
|
<term>MAINPID=…</term>
|
||||||
|
|
||||||
<listitem><para>The main process ID (PID) of the service, in
|
<listitem><para>The main process ID (PID) of the service, in case the service manager did not fork
|
||||||
case the service manager did not fork off the process itself.
|
off the process itself. Example: <literal>MAINPID=4711</literal></para></listitem>
|
||||||
Example: <literal>MAINPID=4711</literal></para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>WATCHDOG=1</term>
|
<term>WATCHDOG=1</term>
|
||||||
|
|
||||||
<listitem><para>Tells the service manager to update the
|
<listitem><para>Tells the service manager to update the watchdog timestamp. This is the keep-alive
|
||||||
watchdog timestamp. This is the keep-alive ping that services
|
ping that services need to issue in regular intervals if <varname>WatchdogSec=</varname> is enabled
|
||||||
need to issue in regular intervals if
|
for it. See
|
||||||
<varname>WatchdogSec=</varname> is enabled for it. See
|
|
||||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
for information how to enable this functionality and
|
for information how to enable this functionality and
|
||||||
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
for the details of how the service can check whether the
|
for the details of how the service can check whether the watchdog is enabled. </para></listitem>
|
||||||
watchdog is enabled. </para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>WATCHDOG=trigger</term>
|
<term>WATCHDOG=trigger</term>
|
||||||
|
|
||||||
<listitem><para>Tells the service manager that the service detected an internal error that should be handled by
|
<listitem><para>Tells the service manager that the service detected an internal error that should be
|
||||||
the configured watchdog options. This will trigger the same behaviour as if <varname>WatchdogSec=</varname> is
|
handled by the configured watchdog options. This will trigger the same behaviour as if
|
||||||
enabled and the service did not send <literal>WATCHDOG=1</literal> in time. Note that
|
<varname>WatchdogSec=</varname> is enabled and the service did not send <literal>WATCHDOG=1</literal>
|
||||||
<varname>WatchdogSec=</varname> does not need to be enabled for <literal>WATCHDOG=trigger</literal> to trigger
|
in time. Note that <varname>WatchdogSec=</varname> does not need to be enabled for
|
||||||
the watchdog action. See
|
<literal>WATCHDOG=trigger</literal> to trigger the watchdog action. See
|
||||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
information about the watchdog behavior. </para></listitem>
|
for information about the watchdog behavior. </para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>WATCHDOG_USEC=…</term>
|
<term>WATCHDOG_USEC=…</term>
|
||||||
|
|
||||||
<listitem><para>Reset <varname>watchdog_usec</varname> value during runtime.
|
<listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. Notice that this is not
|
||||||
Notice that this is not available when using <function>sd_event_set_watchdog()</function>
|
available when using <function>sd_event_set_watchdog()</function> or
|
||||||
or <function>sd_watchdog_enabled()</function>.
|
<function>sd_watchdog_enabled()</function>. Example :
|
||||||
Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem>
|
<literal>WATCHDOG_USEC=20000000</literal></para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>EXTEND_TIMEOUT_USEC=…</term>
|
<term>EXTEND_TIMEOUT_USEC=…</term>
|
||||||
|
|
||||||
<listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
|
<listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout
|
||||||
corresponding the current state. The value specified is a time in microseconds during which the service must
|
corresponding the current state. The value specified is a time in microseconds during which the
|
||||||
send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the
|
service must send a new message. A service timeout will occur if the message isn't received, but only
|
||||||
current state is beyond the original maximum times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>,
|
if the runtime of the current state is beyond the original maximum times of
|
||||||
and <varname>TimeoutStopSec=</varname>.
|
<varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, and
|
||||||
See <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<varname>TimeoutStopSec=</varname>. See
|
||||||
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
for effects on the service timeouts.</para></listitem>
|
for effects on the service timeouts.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
@ -266,33 +254,37 @@
|
|||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>FDSTOREREMOVE=1</term>
|
<term>FDSTOREREMOVE=1</term>
|
||||||
|
|
||||||
<listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with
|
<listitem><para>Removes file descriptors from the file descriptor store. This field needs to be
|
||||||
<varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem>
|
combined with <varname>FDNAME=</varname> to specify the name of the file descriptors to
|
||||||
|
remove.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>FDNAME=…</term>
|
<term>FDNAME=…</term>
|
||||||
|
|
||||||
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted
|
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the
|
||||||
file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file
|
submitted file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for
|
||||||
descriptors to remove. This name is passed to the service during activation, and may be queried using
|
the file descriptors to remove. This name is passed to the service during activation, and may be
|
||||||
|
queried using
|
||||||
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
|
<citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File
|
||||||
descriptors submitted without this field set, will implicitly get the name <literal>stored</literal>
|
descriptors submitted without this field set, will implicitly get the name <literal>stored</literal>
|
||||||
assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to
|
assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be
|
||||||
all of them. In order to assign different names to submitted file descriptors, submit them in separate
|
assigned to all of them. In order to assign different names to submitted file descriptors, submit
|
||||||
invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII
|
them in separate invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist
|
||||||
characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a
|
of arbitrary ASCII characters except control characters or <literal>:</literal>. It may not be longer
|
||||||
submitted name does not follow these restrictions, it is ignored.</para></listitem>
|
than 255 characters. If a submitted name does not follow these restrictions, it is
|
||||||
|
ignored.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>FDPOLL=0</term>
|
<term>FDPOLL=0</term>
|
||||||
|
|
||||||
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the stored
|
<listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the
|
||||||
file descriptors regardless of whether or not they are pollable. As this option disables automatic cleanup
|
stored file descriptors regardless of whether or not they are pollable. As this option disables
|
||||||
of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to ensure proper manual cleanup.
|
automatic cleanup of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to
|
||||||
Use of this option is not generally recommended except for when automatic cleanup has unwanted behavior such
|
ensure proper manual cleanup. Use of this option is not generally recommended except for when
|
||||||
as prematurely discarding file descriptors from the store.</para></listitem>
|
automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the
|
||||||
|
store.</para></listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
@ -309,23 +301,22 @@
|
|||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
|
||||||
<para>It is recommended to prefix variable names that are not
|
<para>It is recommended to prefix variable names that are not listed above with <varname>X_</varname> to
|
||||||
listed above with <varname>X_</varname> to avoid namespace
|
avoid namespace clashes.</para>
|
||||||
clashes.</para>
|
|
||||||
|
|
||||||
<para>Note that systemd will accept status data sent from a
|
<para>Note that systemd will accept status data sent from a service only if the
|
||||||
service only if the <varname>NotifyAccess=</varname> option is
|
<varname>NotifyAccess=</varname> option is correctly set in the service definition file. See
|
||||||
correctly set in the service definition file. See
|
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||||||
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
details.</para>
|
||||||
for details.</para>
|
|
||||||
|
|
||||||
<para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only if either
|
<para>Note that <function>sd_notify()</function> notifications may be attributed to units correctly only
|
||||||
the sending process is still around at the time PID 1 processes the message, or if the sending process is
|
if either the sending process is still around at the time PID 1 processes the message, or if the sending
|
||||||
explicitly runtime-tracked by the service manager. The latter is the case if the service manager originally forked
|
process is explicitly runtime-tracked by the service manager. The latter is the case if the service
|
||||||
off the process, i.e. on all processes that match <varname>NotifyAccess=</varname><option>main</option> or
|
manager originally forked off the process, i.e. on all processes that match
|
||||||
<varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit sends an
|
<varname>NotifyAccess=</varname><option>main</option> or
|
||||||
<function>sd_notify()</function> message and immediately exits, the service manager might not be able to properly
|
<varname>NotifyAccess=</varname><option>exec</option>. Conversely, if an auxiliary process of the unit
|
||||||
attribute the message to the unit, and thus will ignore it, even if
|
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>
|
<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
|
<para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
|
||||||
@ -335,22 +326,15 @@
|
|||||||
service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
|
service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
|
||||||
unit.</para>
|
unit.</para>
|
||||||
|
|
||||||
<para><function>sd_notifyf()</function> is similar to
|
<para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a
|
||||||
<function>sd_notify()</function> but takes a
|
<function>printf()</function>-like format string plus arguments.</para>
|
||||||
<function>printf()</function>-like format string plus
|
|
||||||
arguments.</para>
|
|
||||||
|
|
||||||
<para><function>sd_pid_notify()</function> and
|
<para><function>sd_pid_notify()</function> and <function>sd_pid_notifyf()</function> are similar to
|
||||||
<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
|
||||||
<function>sd_notify()</function> and
|
as originating PID for the message as first argument. This is useful to send notification messages on
|
||||||
<function>sd_notifyf()</function> but take a process ID (PID) to
|
behalf of other processes, provided the appropriate privileges are available. If the PID argument is
|
||||||
use as originating PID for the message as first argument. This is
|
specified as 0, the process ID of the calling process is used, in which case the calls are fully
|
||||||
useful to send notification messages on behalf of other processes,
|
equivalent to <function>sd_notify()</function> and <function>sd_notifyf()</function>.</para>
|
||||||
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>
|
<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
|
but takes an additional array of file descriptors. These file descriptors are sent along the notification
|
||||||
@ -361,10 +345,9 @@
|
|||||||
that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
|
that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
|
||||||
immediately closed on reception.</para>
|
immediately closed on reception.</para>
|
||||||
|
|
||||||
<para><function>sd_notify_barrier()</function> allows the caller to
|
<para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of
|
||||||
synchronize against reception of previously sent notification messages
|
previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a
|
||||||
and uses the <varname>BARRIER=1</varname> command. It takes a relative
|
relative <varname>timeout</varname> value in microseconds which is passed to
|
||||||
<varname>timeout</varname> value in microseconds which is passed to
|
|
||||||
<citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
|
<citerefentry><refentrytitle>ppoll</refentrytitle><manvolnum>2</manvolnum>
|
||||||
</citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.
|
</citerefentry>. A value of UINT64_MAX is interpreted as infinite timeout.
|
||||||
</para>
|
</para>
|
||||||
@ -373,14 +356,15 @@
|
|||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Return Value</title>
|
<title>Return Value</title>
|
||||||
|
|
||||||
<para>On failure, these calls return a negative errno-style error code. If <varname>$NOTIFY_SOCKET</varname> was
|
<para>On failure, these calls return a negative errno-style error code. If
|
||||||
not set and hence no status message could be sent, 0 is returned. If the status was sent, these functions return a
|
<varname>$NOTIFY_SOCKET</varname> was not set and hence no status message could be sent, 0 is
|
||||||
positive value. In order to support both service managers that implement this scheme and those which do not, it is
|
returned. If the status was sent, these functions return a positive value. In order to support both
|
||||||
generally recommended to ignore the return value of this call. Note that the return value simply indicates whether
|
service managers that implement this scheme and those which do not, it is generally recommended to ignore
|
||||||
the notification message was enqueued properly, it does not reflect whether the message could be processed
|
the return value of this call. Note that the return value simply indicates whether the notification
|
||||||
|
message was enqueued properly, it does not reflect whether the message could be processed
|
||||||
successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
|
successfully. Specifically, no error is returned when a file descriptor is attempted to be stored using
|
||||||
<varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file descriptors (see
|
<varname>FDSTORE=1</varname> but the service is not actually configured to permit storing of file
|
||||||
above).</para>
|
descriptors (see above).</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
@ -389,27 +373,21 @@
|
|||||||
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
|
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
|
||||||
<xi:include href="threads-aware.xml" xpointer="getenv"/>
|
<xi:include href="threads-aware.xml" xpointer="getenv"/>
|
||||||
|
|
||||||
<para>These functions send a single datagram with the
|
<para>These functions send a single datagram with the state string as payload to the socket referenced in
|
||||||
state string as payload to the socket referenced in the
|
the <varname>$NOTIFY_SOCKET</varname> environment variable. If the first character of
|
||||||
<varname>$NOTIFY_SOCKET</varname> environment variable. If the
|
<varname>$NOTIFY_SOCKET</varname> is <literal>/</literal> or <literal>@</literal>, the string is
|
||||||
first character of <varname>$NOTIFY_SOCKET</varname> is
|
understood as an <constant>AF_UNIX</constant> or Linux abstract namespace socket (respectively), and in
|
||||||
<literal>/</literal> or <literal>@</literal>, the string is understood
|
both cases the datagram is accompanied by the process credentials of the sending service, using
|
||||||
as an <constant>AF_UNIX</constant> or Linux abstract namespace socket
|
SCM_CREDENTIALS. If the string starts with <literal>vsock:</literal> then the string is understood as an
|
||||||
(respectively), and in both cases the datagram is accompanied by the
|
<constant>AF_VSOCK</constant> address, which is useful for hypervisors/VMMs or other processes on the
|
||||||
process credentials of the sending service, using SCM_CREDENTIALS. If
|
host to receive a notification when a virtual machine has finished booting. Note that in case the
|
||||||
the string starts with <literal>vsock:</literal> then the string is
|
hypervisor does not support <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>,
|
||||||
understood as an <constant>AF_VSOCK</constant> address, which is useful
|
<constant>SOCK_SEQPACKET</constant> will be used instead. The address should be in the form:
|
||||||
for hypervisors/VMMs or other processes on the host to receive a
|
<literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock, the CID is mandatory and cannot
|
||||||
notification when a virtual machine has finished booting. Note that in
|
be <literal>VMADDR_CID_ANY</literal>. Note that PID1 will send the VSOCK packets from a privileged port
|
||||||
case the hypervisor does not support <constant>SOCK_DGRAM</constant>
|
(i.e.: lower than 1024), as an attempt to address concerns that unprivileged processes in the guest might
|
||||||
over <constant>AF_VSOCK</constant>, <constant>SOCK_SEQPACKET</constant>
|
try to send malicious notifications to the host, driving it to make destructive decisions based on
|
||||||
will be used instead. The address should be in the form:
|
them.</para>
|
||||||
<literal>vsock:CID:PORT</literal>. Note that unlike other uses of vsock,
|
|
||||||
the CID is mandatory and cannot be <literal>VMADDR_CID_ANY</literal>.
|
|
||||||
Note that PID1 will send the VSOCK packets from a privileged port
|
|
||||||
(i.e.: lower than 1024), as an attempt to address concerns that unprivileged
|
|
||||||
processes in the guest might try to send malicious notifications to the
|
|
||||||
host, driving it to make destructive decisions based on them.</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
@ -419,11 +397,9 @@
|
|||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><varname>$NOTIFY_SOCKET</varname></term>
|
<term><varname>$NOTIFY_SOCKET</varname></term>
|
||||||
|
|
||||||
<listitem><para>Set by the service manager for supervised
|
<listitem><para>Set by the service manager for supervised processes for status and start-up
|
||||||
processes for status and start-up completion notification.
|
completion notification. This environment variable specifies the socket
|
||||||
This environment variable specifies the socket
|
<function>sd_notify()</function> talks to. See above for details.</para></listitem>
|
||||||
<function>sd_notify()</function> talks to. See above for
|
|
||||||
details.</para></listitem>
|
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
@ -434,8 +410,8 @@
|
|||||||
<example>
|
<example>
|
||||||
<title>Start-up Notification</title>
|
<title>Start-up Notification</title>
|
||||||
|
|
||||||
<para>When a service finished starting up, it might issue the
|
<para>When a service finished starting up, it might issue the following call to notify the service
|
||||||
following call to notify the service manager:</para>
|
manager:</para>
|
||||||
|
|
||||||
<programlisting>sd_notify(0, "READY=1");</programlisting>
|
<programlisting>sd_notify(0, "READY=1");</programlisting>
|
||||||
</example>
|
</example>
|
||||||
@ -443,8 +419,7 @@
|
|||||||
<example>
|
<example>
|
||||||
<title>Extended Start-up Notification</title>
|
<title>Extended Start-up Notification</title>
|
||||||
|
|
||||||
<para>A service could send the following after completing
|
<para>A service could send the following after completing initialization:</para>
|
||||||
initialization:</para>
|
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
sd_notifyf(0, "READY=1\n"
|
sd_notifyf(0, "READY=1\n"
|
||||||
@ -468,9 +443,8 @@ sd_notifyf(0, "STATUS=Failed to start up: %s\n"
|
|||||||
<example>
|
<example>
|
||||||
<title>Store a File Descriptor in the Service Manager</title>
|
<title>Store a File Descriptor in the Service Manager</title>
|
||||||
|
|
||||||
<para>To store an open file descriptor in the service manager,
|
<para>To store an open file descriptor in the service manager, in order to continue operation after a
|
||||||
in order to continue operation after a service restart without
|
service restart without losing state, use <literal>FDSTORE=1</literal>:</para>
|
||||||
losing state, use <literal>FDSTORE=1</literal>:</para>
|
|
||||||
|
|
||||||
<programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
|
<programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1\nFDNAME=foobar", &fd, 1);</programlisting>
|
||||||
</example>
|
</example>
|
||||||
@ -478,12 +452,10 @@ sd_notifyf(0, "STATUS=Failed to start up: %s\n"
|
|||||||
<example>
|
<example>
|
||||||
<title>Eliminating race conditions</title>
|
<title>Eliminating race conditions</title>
|
||||||
|
|
||||||
<para>When the client sending the notifications is not spawned
|
<para>When the client sending the notifications is not spawned by the service manager, it may exit too
|
||||||
by the service manager, it may exit too quickly and the service
|
quickly and the service manager may fail to attribute them correctly to the unit. To prevent such
|
||||||
manager may fail to attribute them correctly to the unit. To
|
races, use <function>sd_notify_barrier()</function> to synchronize against reception of all
|
||||||
prevent such races, use <function>sd_notify_barrier()</function>
|
notifications sent before this call is made.</para>
|
||||||
to synchronize against reception of all notifications sent before
|
|
||||||
this call is made.</para>
|
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
sd_notify(0, "READY=1");
|
sd_notify(0, "READY=1");
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user