* doc/autoconf.texi (Limitations of Builtins): Some information

about `trap'.
Document the Free BSD bug observed by Pavel.

ChangeLog

@@ -1,3 +1,9 @@
+2000-11-10  Akim Demaille  <akim@epita.fr>
+
+	* doc/autoconf.texi (Limitations of Builtins): Some information
+	about `trap'.
+	Document the Free BSD bug observed by Pavel.
+
 2000-11-10  Pavel Roskin  <proski@gnu.org>
 
 	* autoscan.pl (scan_files): Eliminate a warning if no C files

doc/autoconf.texi

@@ -5401,6 +5401,7 @@ as the string composed of a backslash and an n.
 
 @item @command{exit}
 @cindex @command{exit}
+@c FIXME: A better merging between this item and `trap' is welcome.
 Some shell scripts, such as those generated by @command{autoconf}, use a
 trap to clean up before exiting.  If the last shell command exited with
 nonzero status, the trap also exits with nonzero status so that the
@@ -5609,6 +5610,55 @@ expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
 "X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when
 @samp{@var{foo}} contains backslashes.
 
+@item @command{trap}
+@cindex @command{trap}
+It is safe to trap at least the signals 1, 2, 13 and 15.  You can also
+trap 0, i.e., have the trap run when the script end (either via an
+explicit @command{exit}, or the end of the script).
+
+Although @sc{posix} is not absolutely clear on that point, it is widely
+admitted that when entering the trap @samp{$?} should be set to the exit
+status of the last command run before the trap.  The ambiguity can be
+summarized as: ``when the trap is launched by an @command{exit}, what is
+the @emph{last} command run: that before @command{exit}, or exit itself.
+
+Bash considers @command{exit} was the last command, while Zsh and
+Solaris 8 @command{sh} consider that when the trap is run it is
+@emph{still} in the @command{exit}, hence it is the previous exit status
+that the trap receives:
+
+@example
+% cat trap.sh
+trap 'echo $?' 0
+(exit 42); exit 0
+% zsh trap.sh
+42
+% bash trap.sh
+0
+@end example
+
+The portable solution is then simple: when you want to @samp{exit 42},
+run @samp{(exit 42); exit 42}, the first @command{exit} being used to
+set the exit status to 42 for Zsh, and the second to trigger the trap
+and pass 42 as exit status for Bash.
+
+Note that in Bourne shell an unqualified @command{exit} is equivalent to
+@samp{exit $?}, hence you may actually abbreviate it as @samp{(exit 42);
+exit}.
+
+The shell in FreeBSD 4.0 has the following bug: @samp{ $?} is reset to 0
+by empty lines if the code in inside trap.
+
+@example
+$ trap 'false
+
+echo $?' 0
+$ exit
+0
+@end example
+
+@noindent
+Fortunately this bug affects only trap.
 
 @item @command{unset}
 @cindex @command{unset}