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.

1 files changed, 39 insertions, 0 deletions

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