Give more-useful info on a fatal error (Bug#12328).

* doc/emacs/trouble.texi (Crashing): New section, documenting this.
* etc/NEWS: Document the change.
* src/alloc.c [ENABLE_CHECKING]: Do not include <execinfo.h>.
(die) [ENABLE_CHECKING]: Call fatal_error_backtrace instead
of doing the work ourselves.
* src/emacs.c (fatal_error_signal): Let fatal_error_backtrace
do most of the work.
(fatal_error_backtrace): New function, taken from the guts
of the old fatal_error_signal, but with a new option to output
a backtrace.
(shut_down_emacs) [!DOS_NT]: Use strsignal to give more-useful
info about the signal than just its number.
* src/lisp.h (fatal_error_backtrace, emacs_backtrace): New decls.
* src/sysdep.c: Include <execinfo.h>
(emacs_backtrace): New function, taken partly from the previous
code of the 'die' function.
(emacs_abort): Call fatal_error_backtrace rather than abort.

3 files changed, 46 insertions, 1 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index a4f9985ad85..78f1d2c8e3b 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2012-09-04  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Give more-useful info on a fatal error (Bug#12328).
+        * trouble.texi (Crashing): New section, documenting this.
+
 2012-08-24  Michael Albinus  <michael.albinus@gmx.de>
 
         * cmdargs.texi (General Variables): Setting
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 6357aebc6ff..192a9a2bb28 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -1136,6 +1136,7 @@ Dealing with Emacs Trouble
 * Screen Garbled::      Garbage on the screen.
 * Text Garbled::        Garbage in the text.
 * Memory Full::         How to cope when you run out of memory.
+* Crashing::            What Emacs does when it crashes.
 * After a Crash::       Recovering editing in an Emacs session that crashed.
 * Emergency Escape::    What to do if Emacs stops responding.
 
@@ -1320,7 +1321,7 @@ when you get it, not just free for the manufacturer.
 If you find GNU Emacs useful, please @strong{send a donation} to the
 Free Software Foundation to support our work.  Donations to the Free
 Software Foundation are tax deductible in the US.  If you use GNU Emacs
-at your workplace, please suggest that the company make a donation. 
+at your workplace, please suggest that the company make a donation.
 For more information on how you can help, see
 @url{http://www.gnu.org/help/help.html}.
 
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 025185c583f..1806339e45d 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -149,6 +149,7 @@ Emacs.
 * Screen Garbled::        Garbage on the screen.
 * Text Garbled::          Garbage in the text.
 * Memory Full::           How to cope when you run out of memory.
+* Crashing::              What Emacs does when it crashes.
 * After a Crash::         Recovering editing in an Emacs session that crashed.
 * Emergency Escape::      What to do if Emacs stops responding.
 @end menu
@@ -277,6 +278,44 @@ editing in the same Emacs session.
 out of memory, because the buffer menu needs a fair amount of memory
 itself, and the reserve supply may not be enough.
 
+@node Crashing
+@subsection When Emacs Crashes
+
+  Emacs is not supposed to crash, but if it does, before it exits it
+reports some information about the crash to the standard error stream
+@code{stderr}.  This report may be useful to someone who later debugs
+the same version of Emacs on the same platform.  The format of this
+report depends on the platform, and some platforms support backtraces.
+Here is an example, generated on x86-64 GNU/Linux with version 2.15 of
+the GNU C Library:
+
+@example
+Fatal error 11: Segmentation fault
+Backtrace:
+emacs[0x5094e4]
+emacs[0x4ed3e6]
+emacs[0x4ed504]
+/lib64/libpthread.so.0[0x375220efe0]
+/lib64/libpthread.so.0(read+0xe)[0x375220e08e]
+emacs[0x509af6]
+emacs[0x5acc26]
+emacs[0x5adbfb]
+emacs[0x56566b]
+emacs[0x59bac3]
+emacs[0x565151]
+...
+@end example
+
+@noindent
+The number @samp{11} is the system signal number that corresponds to
+the problem, a segmentation fault here.  The hexadecimal program
+addresses can be useful in debugging sessions.  For example, the GDB
+command @samp{list *0x509af6} prints the source-code lines
+corresponding to the @samp{emacs[0x509af6]} entry in the backtrace.
+
+The three dots at the end indicate that Emacs suppressed further
+backtrace entries, in the interest of brevity.
+
 @node After a Crash
 @subsection Recovery After a Crash