From 38a7c3c0bd2a2d858ad18160eb5f6a709b6cfbb1 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 12 Sep 2017 18:02:18 +0200 Subject: [PATCH] man: complete and rework $SERVICE_RESULT documentation This reworks the paragraph describing $SERVICE_RESULT into a table, and adds two missing entries: "success" and "start-limit-hit". These two entries are then also added to the table explaining the $EXIT_CODE + $EXIT_STATUS variables. Fixes: #6597 --- man/systemd.exec.xml | 84 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 66 insertions(+), 18 deletions(-) diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 707cab28aa..ca7d042d65 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -1955,15 +1955,60 @@ CapabilityBoundingSet=~CAP_B CAP_C Only defined for the service unit type, this environment variable is passed to all ExecStop= and ExecStopPost= processes, and encodes the service - "result". Currently, the following values are defined: protocol (in case of a protocol - violation; if a service did not take the steps required by its unit configuration), timeout - (in case of an operation timeout), exit-code (if a service process exited with a non-zero - exit code; see $EXIT_CODE below for the actual exit code returned), signal - (if a service process was terminated abnormally by a signal; see $EXIT_CODE below for the - actual signal used for the termination), core-dump (if a service process terminated - abnormally and dumped core), watchdog (if the watchdog keep-alive ping was enabled for the - service but it missed the deadline), or resources (a catch-all condition in case a system - operation failed). + "result". Currently, the following values are defined: + + + Defined <varname>$SERVICE_RESULT</varname> values + + + + + + Value + Meaning + + + + + + success + In case the service ran successfully and exited cleanly + + + protocol + In case of a protocol violation: the service did not take the steps required by its unit configuration (specifically what is configured in its Type= setting) + + + timeout + In case of an operation timeout + + + exit-code + If a service process exited with a non-zero exit code; see $EXIT_CODE below for the actual exit code returned. + + + signal + If a service process was terminated abnormally by a signal, without dumping core; see $EXIT_CODE below for the actual signal causing the termination + + + core-dump + If a service process terminated abnormally with a signal and dumped core, also see $EXIT_CODE for the signal causing the termination + + + watchdog + If the watchdog keep-alive ping was enabled for the service but it missed the deadline. + + + start-limit-hit + In case a start limit was applied to the unit and it was hit and the unit hence failed to start. See systemd.unit5's StartLimitIntervalSec= and StartLimitBurst= for details. + + + resources + A catch-all condition in case a system operation failed. + + + +
This environment variable is useful to monitor failure or successful termination of a service. Even though this variable is available in both ExecStop= and ExecStopPost=, it @@ -2001,6 +2046,11 @@ CapabilityBoundingSet=~CAP_B CAP_C + + success + exited + 0 + protocol not set @@ -2010,7 +2060,6 @@ CapabilityBoundingSet=~CAP_B CAP_C exited 0 - timeout killed @@ -2021,26 +2070,22 @@ CapabilityBoundingSet=~CAP_B CAP_C 0, 1, 2, 3, …, 255 - exit-code exited - 0, 1, 2, 1, 2, 3, …, 255 - signal killed HUP, INT, KILL, … - core-dump dumped ABRT, SEGV, QUIT, … - watchdog dumped @@ -2055,15 +2100,18 @@ CapabilityBoundingSet=~CAP_B CAP_C 0, 1, 2, 3, …, 255 - + + start-limit-hit + not set + not set + resources any of the above any of the above - - Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the timeout and watchdog rows above only the signals that systemd sends have been included. + Note: the process may be also terminated by a signal not sent by systemd. In particular the process may send an arbitrary signal to itself in a handler for any of the non-maskable signals. Nevertheless, in the timeout and watchdog rows above only the signals that systemd sends have been included. Moreover, using SuccessExitStatus= additional exit statuses may be declared to indicate clean termination, which is not reflected by this table.