Adding upstream version 256.upstream/256

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 49 insertions, 32 deletions

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index 1b96c83..35c450b 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="sd_notify"
@@ -104,8 +104,8 @@
     <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, and the variable is no longer inherited by child
-    processes.</para>
+    <function>sd_notify()</function> will then silently do nothing, and 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
@@ -270,7 +270,7 @@
         <listitem><para>The exit status of a service or the manager itself. Note that
         <command>systemd</command> currently does not consume this value when sent by services, so this
         assignment is only informational. The manager will send this notification to <emphasis>its</emphasis>
-        notification socket, which may be used to to collect an exit status from the system (a container or
+        notification socket, which may be used to collect an exit status from the system (a container or
         VM) as it shuts down. For example,
         <citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         makes use of this. The value to return may be set via the
@@ -420,8 +420,8 @@
         <term>FDPOLL=0</term>
 
         <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, disables polling of the
-        stored file descriptors regardless of whether or not they are pollable. As this option disables
-        automatic cleanup of the stored file descriptors on EPOLLERR and EPOLLHUP, care must be taken to
+        submitted file descriptors regardless of whether or not they are pollable. As this option disables
+        automatic cleanup of the submitted file descriptors on EPOLLERR and EPOLLHUP, care must be taken to
         ensure proper manual cleanup.  Use of this option is not generally recommended except for when
         automatic cleanup has unwanted behavior such as prematurely discarding file descriptors from the
         store.</para>
@@ -446,9 +446,14 @@
     </variablelist>
 
     <para>The notification messages sent by services are interpreted by the service manager. Unknown
-    assignments may be logged, but are otherwise ignored. Thus, it is not useful to send assignments which
-    are not in this list. The service manager also sends some messages to <emphasis>its</emphasis>
-    notification socket, which are then consumed by the machine or container manager.</para>
+    assignments are ignored. Thus, it is safe (but often without effect) to send assignments which are not
+    in this list. The protocol is extensible, but care should be taken to ensure private extensions are
+    recognizable as such. Specifically, it is recommend to prefix them with <literal>X_</literal> followed by
+    some namespace identifier. The service manager also sends some messages to <emphasis>its</emphasis>
+    notification socket, which may then consumed by a supervising machine or container manager further up the
+    stack. The service manager sends a number of extension fields, for example
+    <varname>X_SYSTEMD_UNIT_ACTIVE=</varname>, for details see
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
   </refsect1>
 
   <refsect1>
@@ -480,17 +485,29 @@
     <constant>AF_VSOCK</constant> address, which is useful for hypervisors/VMMs or other processes on the
     host to receive a notification when a virtual machine has finished booting. Note that in case the
     hypervisor does not support <constant>SOCK_DGRAM</constant> over <constant>AF_VSOCK</constant>,
-    <constant>SOCK_SEQPACKET</constant> will be used instead. The address should be in the form:
-    <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>
-
-    <para>Note that, while using this library should be preferred in order to avoid code duplication, it is
-    also possible to reimplement the simple readiness notification protocol without external dependencies,
-    as demonstrated in the following self-contained example:
-    <programlisting><xi:include href="notify-selfcontained-example.c" parse="text"/></programlisting></para>
+    <constant>SOCK_SEQPACKET</constant> will be used instead. <literal>vsock-stream</literal>,
+    <literal>vsock-dgram</literal> and <literal>vsock-seqpacket</literal> can be used instead of
+    <literal>vsock</literal> to force usage of the corresponding socket type. The address should be in the
+    form: <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>
+
+    <refsect2>
+      <title>Standalone Implementations</title>
+      <para>Note that, while using this library should be preferred in order to avoid code duplication, it is
+      also possible to reimplement the simple readiness notification protocol without external dependencies,
+      as demonstrated in the following self-contained examples from several languages:</para>
+      <refsect3>
+        <title>C</title>
+        <programlisting><xi:include href="notify-selfcontained-example.c" parse="text"/></programlisting>
+      </refsect3>
+      <refsect3>
+        <title>Python</title>
+        <programlisting><xi:include href="notify-selfcontained-example.py" parse="text"/></programlisting>
+      </refsect3>
+    </refsect2>
   </refsect1>
 
   <refsect1>
@@ -526,8 +543,8 @@
 
       <programlisting>
 sd_notifyf(0, "READY=1\n"
-           "STATUS=Processing requests…\n"
-           "MAINPID=%lu",
+              "STATUS=Processing requests…\n"
+              "MAINPID=%lu",
            (unsigned long) getpid());</programlisting>
     </example>
 
@@ -538,7 +555,7 @@ sd_notifyf(0, "READY=1\n"
 
       <programlisting>
 sd_notifyf(0, "STATUS=Failed to start up: %s\n"
-           "ERRNO=%i",
+              "ERRNO=%i",
            strerror_r(errnum, (char[1024]){}, 1024),
            errnum);</programlisting>
     </example>
@@ -580,15 +597,15 @@ sd_notify_barrier(0, 5 * 1000000);
 
   <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>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>
-    </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>