system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-10-07 00:30:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

man/sd_notify: change recommendations about unsupported notifications

Browse source 
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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2023-09-15 08:58:46 +02:00
parent 67da7e9a4f
commit bb8a3296e8
1 changed files with 15 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
man/sd_notify.xml
View file

@ -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>