From: Jason Yundt <jason@jasonyundt.email>
Date: Tue, 17 Sep 2024 18:00:26 +0000 (-0400)
Subject: man: document ShowStatus and SetShowStatus()
X-Git-Tag: v257-rc1~410
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=dfb3155419c5c1bfb9cd2c8735b46c7724d171c4;p=thirdparty%2Fsystemd.git

man: document ShowStatus and SetShowStatus()

SetShowStatus() was added in order to fix #11447. Recently, I ran into
the exact same problem that OP was experiencing in #11447. I wasn’t able
to figure out how to deal with the problem until I found #11447, and it
took me a while to find #11447.

This commit takes what I learned from reading #11447 and adds it to the
documentation. Hopefully, this will make it easier for other people who
run into the same problem in the future.
---

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index 373354050ae..aa4f69deb19 100644
--- a/man/org.freedesktop.systemd1.xml
+++ b/man/org.freedesktop.systemd1.xml
@@ -593,8 +593,6 @@ node /org/freedesktop/systemd1 {
 
     <!--method GetJobBefore is not documented!-->
 
-    <!--method SetShowStatus is not documented!-->
-
     <!--method ListUnitsFiltered is not documented!-->
 
     <!--method ListUnitsByPatterns is not documented!-->
@@ -673,8 +671,6 @@ node /org/freedesktop/systemd1 {
 
     <!--property ConfirmSpawn is not documented!-->
 
-    <!--property ShowStatus is not documented!-->
-
     <!--property DefaultStandardOutput is not documented!-->
 
     <!--property DefaultStandardError is not documented!-->
@@ -1362,6 +1358,24 @@ node /org/freedesktop/systemd1 {
 
       <para><function>ResetFailedUnit()</function> resets the "failed" state of a specific unit.</para>
 
+      <para><function>SetShowStatus()</function> configures the display of status messages during bootup and
+      shutdown. The <varname>mode</varname> parameter can be set to any value that's valid for the
+      <varname>systemd.show_status</varname> kernel parameter. For more information about
+      <varname>systemd.show_status</varname>, see
+      <citerefentry project="man-pages"><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+      The <varname>mode</varname> parameter can also be set to an empty string. When <varname>mode</varname>
+      is set to an empty string, <function>SetShowStatus()</function> will reset
+      <varname>ShowStatus</varname> back to its original value. You can use
+      <function>SetShowStatus()</function> create a service that does something like this:
+      <orderedlist>
+        <listitem><para>Send a D-Bus message that will turn off status messages.</para></listitem>
+        <listitem><para>Block until a reply to that message is received.</para></listitem>
+        <listitem><para>Print multiples lines without being interrupted by status messages.</para></listitem>
+        <listitem><para>Send a D-Bus message that will reset <varname>ShowStatus</varname> back to its
+        original value.</para></listitem>
+      </orderedlist>
+      </para>
+
       <para><function>ResetFailed()</function> resets the "failed" state of all units.</para>
 
       <para><function>ListUnits()</function> returns an array of all currently loaded units. Note that
@@ -1788,6 +1802,12 @@ node /org/freedesktop/systemd1 {
       <para><varname>Environment</varname> encodes the environment block passed to all executed services. It
       may be altered with bus calls such as <function>SetEnvironment()</function> (see above).</para>
 
+      <para><varname>ShowStatus</varname> encodes systemd's current policy for displaying status messages
+      during bootup and shutdown. Its value can be any valid value for the
+      <varname>systemd.show_status</varname> kernel parameter (see
+      <citerefentry project="man-pages"><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
+      It may be altered using <function>SetShowStatus()</function> (see above).</para>
+
       <para><varname>UnitPath</varname> encodes the currently active unit file search path. It is an array of
       file system paths encoded as strings.</para>
 
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 2ff49ff8541..c8ca543b457 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -3001,7 +3001,12 @@ SystemCallErrorNumber=EPERM</programlisting>
 
         <para><option>tty</option> connects standard output to a tty (as configured via <varname>TTYPath=</varname>,
         see below). If the TTY is used for output only, the executed process will not become the controlling process of
-        the terminal, and will not fail or wait for other processes to release the terminal.</para>
+        the terminal, and will not fail or wait for other processes to release the terminal. Note: if a unit
+        tries to print multiple lines to a TTY during bootup or shutdown, then there's a chance that those
+        lines will be broken up by status messages. <function>SetShowStatus()</function> can be used to
+        prevent this problem. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        for details.</para>
 
         <para><option>journal</option> connects standard output with the journal, which is accessible via
         <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. Note
diff --git a/man/systemd.xml b/man/systemd.xml
index ddd190093eb..af1681352e8 100644
--- a/man/systemd.xml
+++ b/man/systemd.xml
@@ -568,7 +568,11 @@
         <listitem><para>Enables display of status messages on the
         console, as controlled via
         <varname>systemd.show_status=1</varname> on the kernel command
-        line.</para></listitem>
+        line.</para>
+        <para>You may want to use <function>SetShowStatus()</function> instead of
+        <constant>SIGRTMIN+20</constant> in order to prevent race conditions. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -579,7 +583,11 @@
         controlled via
         <varname>systemd.show_status=0</varname>
         on the kernel command
-        line.</para></listitem>
+        line.</para>
+        <para>You may want to use <function>SetShowStatus()</function> instead of
+        <constant>SIGRTMIN+21</constant> in order to prevent race conditions. See
+        <citerefentry project="man-pages"><refentrytitle>org.freedesktop.systemd1</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>