30238 plus small tweaks: document the fork behaviour on suspending complex

builtins

2 files changed, 22 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index d8a426b01..387d0504b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2012-02-22  Peter Stephenson  <pws@csr.com>
+
+	* 30238 with small fixes: Doc/Zsh/jobs.yo: document the fork
+	behaviour on suspending complex builtin execution.
+
 2012-02-20  Barton E. Schaefer  <schaefer@zsh.org>
 
 	* 30242: Src/subst.c: use PREFORK_SINGLE for the right-hand side
@@ -16000,5 +16005,5 @@
 
 *****************************************************
 * This is used by the shell to define $ZSH_PATCHLEVEL
-* $Revision: 1.5591 $
+* $Revision: 1.5592 $
 *****************************************************
diff --git a/Doc/Zsh/jobs.yo b/Doc/Zsh/jobs.yo
index 0369e9745..3baf77f20 100644
--- a/Doc/Zsh/jobs.yo
+++ b/Doc/Zsh/jobs.yo
@@ -37,6 +37,22 @@ when it is typed.
 
 A job being run in the background will suspend if it tries to read
 from the terminal.
+
+Note that if the job running in the foreground is a shell function,
+then suspending it will have the effect of causing the shell to fork.
+This is necessary to separate the function's state from that of the
+parent shell performing the job control, so that the latter can return
+to the command line prompt.  As a result, even if tt(fg) is
+used to continue the job the function will no longer be part of the
+parent shell, and any variables set by the function will not be visible
+in the parent shell.  Thus the behaviour is different from the case
+where the function was never suspended.  Zsh is different from many
+other shells in this regard.
+
+The same behaviour is found when the shell is executing code as the
+right hand side of a pipeline or any complex shell construct such as
+tt(if), tt(for), etc., in order that the entire block of code
+can be managed as a single job.
 cindex(background jobs, I/O)
 cindex(jobs, background, I/O)
 Background jobs are normally allowed to produce output,