diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2015-02-19 04:13:20 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2015-02-19 04:13:20 +0000 |
| commit | e1fe79a9e705e3cab8f632cdbe8e1774cdef2761 (patch) | |
| tree | fcf1e195e4025ca14b7caea13c0da41fca15ea97 /doc/exitcodes.html | |
| parent | c73a41da14650d93801a59b85757a73741be986f (diff) | |
| download | execline-e1fe79a9e705e3cab8f632cdbe8e1774cdef2761.tar.xz | |
- exit code overhaul: forx, forbacktickx, loopwhilex, if, ifelse, ifte,v2.1.0.0
ifthenelse
- new -o option to forx, forbacktickx, loopwhilex
- documentation updated
- version: rc for 2.1.0.0
Diffstat (limited to 'doc/exitcodes.html')
| -rw-r--r-- | doc/exitcodes.html | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/exitcodes.html b/doc/exitcodes.html new file mode 100644 index 0000000..4b8afda --- /dev/null +++ b/doc/exitcodes.html @@ -0,0 +1,97 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>execline: exit codes</title> + <meta name="Description" content="execline: exit codes" /> + <meta name="Keywords" content="execline exit codes" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">execline</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> How to propagate exit codes up a process dynasty </h1> + +<p> + Say we have a parent process <em>P</em>, child of a grandparent process +<em>G</em>, spawning a child process <em>C</em> and waiting for it. +Either <em>C</em> dies normally with an exit code from 0 to 255, or it is +killed by a signal. + How can we make sure that <em>P</em> reports to <em>G</em> what happened +to <em>C</em>, with as much precision as possible ? +</p> + +<p> + The problem is, there's more information in a wstat (the +structure filled in by +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/waitpid.html">waitpid()</a>) +than a process can report by +simply exiting. <em>P</em> could exit with the same exit code as <em>C</em>, +but then what should it do if C has been killed by a signal ? +</p> + +<p> + An idea is to have <em>P</em> kill itself with the same signal that killed +<em>C</em>. +But that's actually not right, because <em>P</em> itself could be killed by a +signal from another source, and G needs that information. "<em>P</em> has been +killed by a signal" and "<em>C</em> has been killed by a signal" are two +different informations, so they should not be reported in the same way. +</p> + +<p> + So, any way you look at it, there is always more information than we +can report. +</p> + +<p> +Shells have their own +<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_08_02">convention</a> +for reporting crashes, but since any exit code greater than 127 is reported +as is, the information given by the shell is unreliable: "child exited 129" +and "child was killed by SIGHUP" are indistinguishable. When shells get +nested, all bets are off - the information conveyed by exit codes becomes +devoid of meaning pretty fast. We need something better. +</p> + +<h2> execline's solution </h2> + +<p> +execline commands such as <a href="forx.html">forx</a>, that can report +a child's exit code, proceed that way when they're in the position of +<em>P</em>: +</p> + +<ul> + <li> If <em>C</em> was killed by a signal: <em>P</em> exits 128 plus the +signal number. </li> + <li> If <em>C</em> exited 128 or more: <em>P</em> exits 128. </li> + <li> Else, <em>P</em> exits with the same code as <em>C</em>. </li> +</ul> + +<p> + Rationale: +</p> + +<ul> + <li> 128+ exit codes are extremely rare and should report really +problematic conditions; commands usually exit 127 or less. If <em>C</em> +exits 128+, it's more important to convey the information +"something really bad happened, but the <em>C</em> process itself was not +killed by a signal" than the exact nature of the event. </li> + <li> Commands following that convention can be nested. If <em>P</em> exits +129+, <em>G</em> knows that <em>C</em> was +killed by a signal. If <em>G</em> also needs to report that to its parent, +it will exit 128: <em>G</em>'s parent will not know the signal number, but +it will know that <em>P</em> reported 128 or more, so either <em>C</em> or +a scion of <em>C</em> had problems. </li> + <li> Exact information is reported in the common case. </li> +</ul> + +</body> +</html> |