From 7f3614e5479446bbd5a2bdf6aed4962e8d803e35 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Tue, 29 Oct 2019 18:07:07 +0100
Subject: run: propagate return code/status from the child

Fixes #13756. We were returning things that didn't make much sense:
we would always use the exit_code value as the exit code. But it sometimes
contains a exit code from the process, and sometimes the number of a signal
that was used to kill the process. We would also ignore SuccessExitStatus=
and in general whether systemd thinks the service exited successfully
(hence the issue in #13756, where systemd would return success/SIGTERM,
but we'd just look at the SIGTERM part.)

If we are doing --wait, let's always propagate the exit code/status from
the child.

While at it, make the documentation useful.
---
 man/systemd-run.xml | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

(limited to 'man/systemd-run.xml')

diff --git a/man/systemd-run.xml b/man/systemd-run.xml
index 610c3acd37..3a1d18dae9 100644
--- a/man/systemd-run.xml
+++ b/man/systemd-run.xml
@@ -399,8 +399,13 @@
   <refsect1>
     <title>Exit status</title>
 
-    <para>On success, 0 is returned, a non-zero failure
-    code otherwise.</para>
+    <para>On success, 0 is returned. If <command>systemd-run</command> failed to start the service, a
+    non-zero return value will be returned. If <command>systemd-run</command> waits for the service to
+    terminate, the return value will be propagated from the service. 0 will be returned on success, including
+    all the cases where systemd considers a service to have exited cleanly, see the discussion of
+    <varname>SuccessExitStatus=</varname> in
+    <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
   </refsect1>
 
   <refsect1>
@@ -503,6 +508,16 @@ There is a screen on:
 
       <programlisting>$ loginctl enable-linger</programlisting>
     </example>
+
+    <example>
+      <title>Return value</title>
+
+      <programlisting>$ systemd-run --user --wait true
+$ systemd-run --user --wait -p SuccessExitStatus=11 bash -c 'exit 11'
+$ systemd-run --user --wait -p SuccessExitStatus=SIGUSR1 bash -c 'kill -SIGUSR1 $$$$'</programlisting>
+
+      <para>Those three invocations will succeed, i.e. terminate with an exit code of 0.</para>
+    </example>
   </refsect1>
 
   <refsect1>
-- 
cgit v1.2.3