@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Dealing with Common Problems
* 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
editing in the same Emacs session.
Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
-out of memory, because the buffer menu needs a fair amount of memory
+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
+
+@cindex crash report
+@cindex backtrace
+@cindex @file{emacs_backtrace.txt} file, MS-Windows
+ Emacs is not supposed to crash, but if it does, it produces a
+@dfn{crash report} prior to exiting. The crash report is printed to
+the standard error stream. If Emacs was started from a graphical
+desktop on a GNU or Unix system, the standard error stream is commonly
+redirected to a file such as @file{~/.xsession-errors}, so you can
+look for the crash report there. On MS-Windows, the crash report is
+written to a file named @file{emacs_backtrace.txt} in the current
+directory of the Emacs process, in addition to the standard error
+stream.
+
+ The format of the crash report depends on the platform. On some
+platforms, such as those using the GNU C Library, the crash report
+includes a @dfn{backtrace} describing the execution state prior to
+crashing, which can be used to help debug the crash. Here is an
+example for a GNU system:
+
+@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]
+@dots{}
+@end example
+
+@noindent
+The number @samp{11} is the system signal number corresponding to the
+crash---in this case a segmentation fault. The hexadecimal numbers
+are program addresses, which can be associated with source code lines
+using a debugging tool. For example, the GDB command
+@samp{list *0x509af6} prints the source-code lines corresponding to
+the @samp{emacs[0x509af6]} entry. If your system has the
+@command{addr2line} utility, the following shell command outputs a
+backtrace with source-code line numbers:
+
+@example
+sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
+ addr2line -C -f -i -p -e @var{bindir}/@var{emacs-binary}
+@end example
+
+@noindent
+Here, @var{backtrace} is the name of a text file containing a copy of
+the backtrace, @var{bindir} is the name of the directory that
+contains the Emacs executable, and @var{emacs-binary} is the name of
+the Emacs executable file, normally @file{emacs} on GNU and Unix
+systems and @file{emacs.exe} on MS-Windows and MS-DOS. Omit the
+@option{-p} option if your version of @command{addr2line} is too old
+to have it.
+
+@cindex core dump
+ Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
+systems that support core files. A core dump is a file containing
+voluminous data about the state of the program prior to the crash,
+usually examined by loading it into a debugger such as GDB@. On many
+platforms, core dumps are disabled by default, and you must explicitly
+enable them by running the shell command @samp{ulimit -c unlimited}
+(e.g., in your shell startup script).
+
@node After a Crash
@subsection Recovery After a Crash
@file{core.emacs}, so that another crash won't overwrite it.
To use this script, run @code{gdb} with the file name of your Emacs
-executable and the file name of the core dump, e.g. @samp{gdb
+executable and the file name of the core dump, e.g., @samp{gdb
/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the
recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}.
Then type the command @code{ybuffer-list} to see which buffers are
from Emacs using the @code{debbugs} package, which can be downloaded
via the Package Menu (@pxref{Packages}). This package provides the
command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x
-debbugs-gnu-search} to search for a specific bug.
+debbugs-gnu-search} to search for a specific bug. User tags, applied
+by the Emacs maintainers, are shown by @kbd{M-x debbugs-gnu-usertags}.
@item
The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
(If you want to suggest an improvement or new feature, use the same
address.) If you cannot send mail from inside Emacs, you can copy the
text of your report to your normal mail client (if your system
-supports it, you can type @kbd{C-c m} to have Emacs do this for you)
+supports it, you can type @kbd{C-c M-i} to have Emacs do this for you)
and send it to that address. Or you can simply send an email to that
address describing the problem.
@section Contributing to Emacs Development
@cindex contributing to Emacs
-If you would like to help pretest Emacs releases to assure they work
-well, or if you would like to work on improving Emacs, please contact
-the maintainers at @email{emacs-devel@@gnu.org}. A pretester
-should be prepared to investigate bugs as well as report them. If you'd
-like to work on improving Emacs, please ask for suggested projects or
-suggest your own ideas.
+If you would like to work on improving Emacs, please contact
+the maintainers at @email{emacs-devel@@gnu.org}. You can ask for
+suggested projects or suggest your own ideas.
If you have already written an improvement, please tell us about it. If
you have not yet started work, it is useful to contact
HCoop / bpt / emacs.git / blobdiff