20024: Improve documentation for TRAPNAL functions

2 files changed, 23 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index fe17300e6..65fc74d68 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2004-06-08  Peter Stephenson  <pws@csr.com>
+
+	* 20024: Doc/Zsh/func.yo: Improve documentation for TRAPNAL
+	functions.
+
 2004-06-03  Felix Rosencrantz <f_rosencrantz@yahoo.com>
 
         * 20002: Src/Zle/compmatch.c: Fix a problem with an inconsistent
diff --git a/Doc/Zsh/func.yo b/Doc/Zsh/func.yo
index d6bc54599..3399ae7b6 100644
--- a/Doc/Zsh/func.yo
+++ b/Doc/Zsh/func.yo
@@ -193,6 +193,24 @@ The signal number will be passed as the first parameter to the function.
 
 If a function of this form is defined and null,
 the shell and processes spawned by it will ignore tt(SIG)var(NAL).
+
+The return value from the function is handled specially.  If it is
+zero, the signal is assumed to have been handled, and execution continues
+normally.  Otherwise, the normal effect of the signal is produced;
+if this causes execution to terminate, the status returned to the shell is
+the status returned from the function.
+
+Programs terminated by uncaught signals typically return the status 128
+plus the signal number.  Hence the following causes the handler for
+tt(SIGINT) to print a message, then mimic the usual effect of the signal.
+
+example(TRAPINT() {
+  print "Caught SIGINT, aborting."
+  return $(( 128 + $1 ))
+})
+
+The functions tt(TRAPZERR), tt(TRAPDEBUG) and tt(TRAPEXIT) are never
+executed inside other traps.
 )
 findex(TRAPDEBUG)
 item(tt(TRAPDEBUG))(