From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Fri, 15 Sep 2023 06:58:46 +0000 (+0200)
Subject: man/sd_notify: change recommendations about unsupported notifications
X-Git-Tag: v255-rc1~510^2~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bb8a3296e8837c8dbc8f0ccc5e5fc735de73ad50;p=thirdparty%2Fsystemd.git

man/sd_notify: change recommendations about unsupported notifications

In principle, arbitrary notifications may be sent via sd_notify. But in
practice, this is not useful at all, since the manager only accepts
notifications from services and ignores anything except a few specific
ones. The others will be logged if debugging is enabled. OTOH, the manager
produces EXIT_STATUS, but nothing in systemd looks at it, which is rather
confusing.

So remove the recommendation to use X_ prefixes, and instead say that other
messages will be ignored. Also, mention that mkosi uses this. Having an example
may be useful to understand what is going on.

Strangely, this is the first reference to mkosi in our man pages. Even more
strangely, debian is the only place which hosts the mkosi man page (among
the sites we have definitions for), so I linked to that version.
---

diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index a6a9a9bed8b..0f2f9314775 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -258,7 +258,8 @@
         <term>BUSERROR=…</term>
 
         <listitem><para>If a service fails, the D-Bus error-style error code. Example:
-        <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para>
+        <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal>. Note that this assignment is
+        currently not used by <command>systemd</command>.</para>
 
         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
       </varlistentry>
@@ -266,8 +267,15 @@
       <varlistentry>
         <term>EXIT_STATUS=…</term>
 
-        <listitem><para>If a service exits, the return value of its <function>main()</function> function.
-        </para>
+        <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
+        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
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        <command>exit</command> verb.</para>
 
         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
       </varlistentry>
@@ -434,8 +442,10 @@
       </varlistentry>
     </variablelist>
 
-    <para>It is recommended to prefix variable names that are not listed above with <literal>X_</literal> to
-    avoid namespace clashes.</para>
+    <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>
   </refsect1>
 
   <refsect1>