Users/18033: Documentation for exit and ERR_EXIT.

Notes about interaction with asynchronous jobs such as process
substitution and multios.

4 files changed, 31 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 5e6333524..5f9adbc59 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2013-10-16  Peter Stephenson  <p.w.stephenson@ntlworld.com>
+
+	* Users/18033: Doc/Zsh/builtins.yo, Doc/Zsh/jobs.yo,
+	Doc/Zsh/options.yo: try to document interaction between exit and
+	asynchronous jobs that don't look asynchronous.
+
 2013-10-16  Peter Stephenson  <p.stephenson@samsung.com>
 
 	* 31827: Doc/Zsh/func.yo: options needed for example.  Only
diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index 2cc33d241..1d9fe687a 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -595,6 +595,11 @@ is specified, use the exit status from the last command executed.
 pindex(IGNORE_EOF, use of)
 An EOF condition will also cause the shell to exit, unless
 the tt(IGNORE_EOF) option is set.
+
+See notes at the end of
+ifzman(the section JOBS in in zmanref(zshmisc))\
+ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions
+of the tt(exit) command with jobs.
 )
 findex(export)
 item(tt(export) [ var(name)[tt(=)var(value)] ... ])(
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index 3baf77f20..d9395010a 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -115,3 +115,18 @@ The shell itself always ignores the tt(QUIT) signal.
 Otherwise, signals have the values
 inherited by the shell from its parent
 (but see the tt(TRAP)var(NAL) special functions in noderef(Functions)).
+
+cindex(exiting shell, and asynchronous jobs)
+cindex(asynchronous jobs, and exiting shell)
+cindex(jobs, asynchronous, and exiting shell)
+Certain jobs are run asynchronously by the shell other than those
+explicitly put into the background; even in cases where the shell
+would usually wait for such jobs, an explicit tt(exit) command
+or exit due to the option tt(ERR_EXIT) will cause the shell to
+exit without waiting.  Examples of such asynchronous jobs are
+process substitution, see
+ifzman(the section PROCESS SUBSTITUTION in the zmanref(zshexpn) manual page)\
+ifnzman(noderef(Process Substitution)), and the handler processes for
+multios, see
+ifzman(the section MULTIOS in the zmanref(zshmisc) manual page)\
+ifnzman(the section Multios in noderef(Redirection)).
diff --git a/Doc/Zsh/options.yo b/Doc/Zsh/options.yo
index 90552157f..3c6ea63b8 100644
--- a/Doc/Zsh/options.yo
+++ b/Doc/Zsh/options.yo
@@ -1553,6 +1553,11 @@ the trap.  If the option tt(DEBUG_BEFORE_CMD) is set,
 as it is by default, and the option tt(ERR_EXIT) is found to have been set
 on exit, then the command for which the tt(DEBUG) trap is being executed is
 skipped.  The option is restored after the trap exits.
+
+Exiting due to tt(ERR_EXIT) has certain interactions with asynchronous
+jobs noted in
+ifzman(the section JOBS in in zmanref(zshmisc))\
+ifnzman(noderef(Jobs & Signals)).
 )
 pindex(ERR_RETURN)
 pindex(NO_ERR_RETURN)